[159] | 1 | .\" RoarAudio |
---|
[4612] | 2 | .TH "roartut" "7" "November 2010" "RoarAudio" "System Manager's Manual: RoarAuido" |
---|
[159] | 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 |
---|
[4610] | 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 | |
---|
[4649] | 74 | if ( roar_vs_run(vss, &err) == \-1 ) { |
---|
[4610] | 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: |
---|
[4649] | 82 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == \-1 ) { |
---|
[4610] | 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 | |
---|
[4649] | 102 | if ( roar_vs_run(vss, &err) == \-1 ) { |
---|
[4610] | 103 | roar_vio_printf(roar_stderr, "Error: can not loop: %s\n", roar_vs_strerr(err)); |
---|
| 104 | } |
---|
| 105 | |
---|
[4649] | 106 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == \-1 ) { |
---|
[4610] | 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. |
---|
[159] | 120 | |
---|
| 121 | .SH "PLAYING A SINE" |
---|
[4610] | 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: |
---|
[159] | 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; |
---|
[4610] | 129 | int bits = 16; |
---|
| 130 | int channels = 1; /* mono */ |
---|
[159] | 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 | |
---|
[4610] | 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]; |
---|
[159] | 147 | int i; |
---|
[4610] | 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. |
---|
[159] | 166 | |
---|
[4610] | 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; |
---|
[159] | 190 | } |
---|
| 191 | |
---|
[4012] | 192 | Now we want to loop for \fBlength\fR seconds: |
---|
[159] | 193 | while (t < 2*M_PI*freq*length) { |
---|
| 194 | } |
---|
| 195 | |
---|
| 196 | In this loop we need to calculate our samples: |
---|
[4610] | 197 | for (i = 0; i < (sizeof(out)/sizeof(*out)); i++) { |
---|
| 198 | out[i] = 32767.f*sin(t); |
---|
[159] | 199 | t += step; |
---|
| 200 | } |
---|
| 201 | |
---|
[4610] | 202 | The sine is multiplyed by 32767 as our amplitude range for 16 bit signed int is from \-32768 to +32767. |
---|
[159] | 203 | |
---|
| 204 | After we have our current data in \fBout\fR we want to write them to the server: |
---|
[4649] | 205 | if ( roar_vs_write(vss, out, sizeof(out), &err) == \-1 ) { |
---|
[4610] | 206 | roar_vio_printf(roar_stderr, "Error: Can not write audio data to server: %s\n", roar_vs_strerr(err)); |
---|
| 207 | break; |
---|
| 208 | } |
---|
[159] | 209 | |
---|
[4610] | 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. |
---|
[159] | 213 | |
---|
[4610] | 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: |
---|
[4649] | 216 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == \-1 ) { |
---|
[4610] | 217 | roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err)); |
---|
| 218 | return 1; |
---|
| 219 | } |
---|
[159] | 220 | |
---|
| 221 | After adding some standard main() construct we should have something like this: |
---|
[4610] | 222 | //vssin.c: |
---|
| 223 | |
---|
| 224 | #include <roaraudio.h> |
---|
| 225 | #include <math.h> |
---|
[159] | 226 | |
---|
| 227 | int main (void) { |
---|
[4610] | 228 | roar_vs_t * vss; |
---|
[159] | 229 | int rate = ROAR_RATE_DEFAULT; |
---|
[4610] | 230 | int bits = 16; |
---|
| 231 | int channels = 1; /* mono */ |
---|
[159] | 232 | int codec = ROAR_CODEC_DEFAULT; |
---|
[4610] | 233 | float freq = 523.2; /* middle C */ |
---|
| 234 | float step = M_PI*2*freq/rate; /* how much time per sample we have to encode ... */ |
---|
[159] | 235 | float t = 0; /* current time */ |
---|
| 236 | float length = 5; /* 5 sec */ |
---|
[4610] | 237 | int16_t out[1024]; |
---|
| 238 | size_t i; |
---|
| 239 | int err; |
---|
[159] | 240 | |
---|
[4610] | 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; |
---|
[159] | 245 | } |
---|
| 246 | |
---|
| 247 | while (t < 2*M_PI*freq*length) { |
---|
[4610] | 248 | for (i = 0; i < (sizeof(out)/sizeof(*out)); i++) { |
---|
| 249 | out[i] = 32768.f*sin(t); |
---|
[159] | 250 | t += step; |
---|
| 251 | } |
---|
[4610] | 252 | |
---|
[4649] | 253 | if ( roar_vs_write(vss, out, sizeof(out), &err) == \-1 ) { |
---|
[4610] | 254 | roar_vio_printf(roar_stderr, "Error: Can not write audio data to server: %s\n", roar_vs_strerr(err)); |
---|
| 255 | break; |
---|
| 256 | } |
---|
[159] | 257 | } |
---|
| 258 | |
---|
[4649] | 259 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == \-1 ) { |
---|
[4610] | 260 | roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err)); |
---|
| 261 | return 1; |
---|
| 262 | } |
---|
[159] | 263 | |
---|
| 264 | return 0; |
---|
| 265 | } |
---|
| 266 | |
---|
[4610] | 267 | //ll |
---|
| 268 | |
---|
[159] | 269 | To compile and link we can use a command like this one: |
---|
[4610] | 270 | cc \-o vssin vssin.c \-lm `roar\-config \-\-libs \-\-cflags` |
---|
[159] | 271 | |
---|
| 272 | We need to use \fB-lm\fR to link the math library for \fBsin()\fR. |
---|
[4610] | 273 | The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libroar. |
---|
[159] | 274 | |
---|
[4610] | 275 | Now we should have a working binary \fBvssin\fR playing a sin() for 5 sec. |
---|
[159] | 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 |
---|