Changeset 4610:5802dc34dda3 in roaraudio


Ignore:
Timestamp:
11/21/10 04:17:56 (12 years ago)
Author:
phi
Branch:
default
Phase:
public
Message:

updated manpage

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/man7/roartut.7

    r4013 r4610  
    1111.SH "DESCRIPTION" 
    1212This 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. 
     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. 
    15120 
    16121.SH "PLAYING A SINE" 
    17 First of all we need the correct header files to be included: 
     122Now we want to write a application playing a sine for some secs. 
     123We start the same way by including the correct header files: 
    18124 #include <math.h>       /* sin() */ 
    19  #include <stdio.h>      /* *printf*() */ 
    20125 #include <roaraudio.h>  /* libroar */ 
    21126 
    22127After that we need some basic varibales with data about the audio we want to play back: 
    23128 int rate     = ROAR_RATE_DEFAULT; 
    24  int bits     = 8; 
    25  int channels = 1; /* mono */ 
     129 int bits     = 16; 
     130 int channels =  1; /* mono */ 
    26131 
    27132Next we need to set the 'codec'. The codec is how the data is encoded. 
     
    37142 float length = 5; /* 5 sec */ 
    38143 
    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; 
     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]; 
    42147 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 
     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; 
    49190 } 
    50191 
     
    54195 
    55196In 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); 
    58199   t += step; 
    59200  } 
    60201 
    61 The sine is multiplyed by 127 as our amplitude range for 8 bit signed int is from \-128 to +127. 
     202The sine is multiplyed by 32767 as our amplitude range for 16 bit signed int is from \-32768 to +32767. 
    62203 
    63204After 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: 
     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 } 
    72220 
    73221After 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> 
    77226 
    78227 int main (void) { 
     228  roar_vs_t * vss; 
    79229  int rate     = ROAR_RATE_DEFAULT; 
    80   int bits     = 8; 
    81   int channels = 1; /* mono */ 
     230  int bits     = 16; 
     231  int channels =  1; /* mono */ 
    82232  int codec    = ROAR_CODEC_DEFAULT; 
    83   float freq   = 523.2;            /* middle C */ 
    84   float step   = M_PI*2*freq/rate; /* how much time per sample we have to encode ... */ 
     233  float freq = 523.2;            /* middle C */ 
     234  float step = M_PI*2*freq/rate; /* how much time per sample we have to encode ... */ 
    85235  float t      = 0; /* current time */ 
    86236  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; 
    94245  } 
    95246 
    96247  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); 
    99250    t += step; 
    100251   } 
    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  } 
    105263 
    106264  return 0; 
    107265 } 
    108266 
     267 //ll 
     268 
    109269To 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` 
    111271 
    112272We 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 libraor. 
    114  
    115 Now we should have a working binary \fBroarsin\fR playing a sin() for 5 sec. 
     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. 
    116276 
    117277Happy hacking! 
Note: See TracChangeset for help on using the changeset viewer.