Changeset 4610:5802dc34dda3 in roaraudio for doc/man7/roartut.7
- Timestamp:
- 11/21/10 04:17:56 (13 years ago)
- Branch:
- default
- Phase:
- public
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
doc/man7/roartut.7
r4013 r4610 11 11 .SH "DESCRIPTION" 12 12 This tutorial descipes some basics with working with libroar. We will create a simple application 13 that can play some sines. A lot of other examples can be found in RoarAudio's sources in the roarclients 14 directory. 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. 15 120 16 121 .SH "PLAYING A SINE" 17 First of all we need the correct header files to be included: 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: 18 124 #include <math.h> /* sin() */ 19 #include <stdio.h> /* *printf*() */20 125 #include <roaraudio.h> /* libroar */ 21 126 22 127 After that we need some basic varibales with data about the audio we want to play back: 23 128 int rate = ROAR_RATE_DEFAULT; 24 int bits = 8;25 int channels = 1; /* mono */129 int bits = 16; 130 int channels = 1; /* mono */ 26 131 27 132 Next we need to set the 'codec'. The codec is how the data is encoded. … … 37 142 float length = 5; /* 5 sec */ 38 143 39 The final thing we need is a socket to send data to the demon, a buffer to store the audio data and 40 a varibale to go thru the array: 41 int fh;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]; 42 147 int i; 43 char out[1024]; 44 45 To open the connection we use the call \fBroar_simple_play\fR(3): 46 if ( (fh = roar_simple_play(rate, channels, bits, codec, NULL, "sine gen")) == \-1 ) { 47 fprintf(stderr, "Error: can not open playback!\\n"); 48 exit(1); 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; 49 190 } 50 191 … … 54 195 55 196 In this loop we need to calculate our samples: 56 for (i = 0; i < 1024; i++) {57 out[i] = 127*sin(t);197 for (i = 0; i < (sizeof(out)/sizeof(*out)); i++) { 198 out[i] = 32767.f*sin(t); 58 199 t += step; 59 200 } 60 201 61 The sine is multiplyed by 127 as our amplitude range for 8 bit signed int is from \-128 to +127.202 The sine is multiplyed by 32767 as our amplitude range for 16 bit signed int is from \-32768 to +32767. 62 203 63 204 After we have our current data in \fBout\fR we want to write them to the server: 64 write(fh, out, 1024); 65 66 \fBNOTE:\fR In a real application you may want to check the return value but in our simple application 67 we should get \fBSIGPIPE\fR on error and simply die. 68 69 After we are finished with our main loop we have to close the socket to the server. 70 This is done by \fBroar_simple_close\fR(3): 71 roar_simple_close(fh); 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 } 72 220 73 221 After adding some standard main() construct we should have something like this: 74 #include <math.h> /* sin() */ 75 #include <stdio.h> /* *printf*() */ 76 #include <roaraudio.h> /* libroar */ 222 //vssin.c: 223 224 #include <roaraudio.h> 225 #include <math.h> 77 226 78 227 int main (void) { 228 roar_vs_t * vss; 79 229 int rate = ROAR_RATE_DEFAULT; 80 int bits = 8;81 int channels = 1; /* mono */230 int bits = 16; 231 int channels = 1; /* mono */ 82 232 int codec = ROAR_CODEC_DEFAULT; 83 float freq 84 float step 233 float freq = 523.2; /* middle C */ 234 float step = M_PI*2*freq/rate; /* how much time per sample we have to encode ... */ 85 235 float t = 0; /* current time */ 86 236 float length = 5; /* 5 sec */ 87 int fh; 88 int i; 89 char out[1024]; 90 91 if ( (fh = roar_simple_play(rate, channels, bits, codec, NULL, "sine gen")) == \-1 ) { 92 fprintf(stderr, "Error: can not open playback!\\n"); 93 exit(1); 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; 94 245 } 95 246 96 247 while (t < 2*M_PI*freq*length) { 97 for (i = 0; i < 1024; i++) {98 out[i] = 127*sin(t);248 for (i = 0; i < (sizeof(out)/sizeof(*out)); i++) { 249 out[i] = 32768.f*sin(t); 99 250 t += step; 100 251 } 101 write(fh, out, 1024); 102 } 103 104 roar_simple_close(fh); 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 } 105 263 106 264 return 0; 107 265 } 108 266 267 //ll 268 109 269 To compile and link we can use a command like this one: 110 cc \-o roarsin roarsin.c \-lm `roar\-config \-\-libs \-\-cflags`270 cc \-o vssin vssin.c \-lm `roar\-config \-\-libs \-\-cflags` 111 271 112 272 We need to use \fB-lm\fR to link the math library for \fBsin()\fR. 113 The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libr aor.114 115 Now we should have a working binary \fB roarsin\fR playing a sin() for 5 sec.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. 116 276 117 277 Happy hacking!
Note: See TracChangeset
for help on using the changeset viewer.