Changeset 4610:5802dc34dda3 in roaraudio for doc

Timestamp:

11/21/10 04:17:56 (13 years ago)

Author:

phi

Branch:

default

Phase:

public

Message:

updated manpage

File:

• doc/man7/roartut.7 (modified) (3 diffs)

doc/man7/roartut.7

@@ -11 +11 @@
 .SH "DESCRIPTION"
 This tutorial descipes some basics with working with libroar. We will create a simple application
-that can play some sines. A lot of other examples can be found in RoarAudio's sources in the roarclients
-directory.
+that can play a file and one that can play some sines.
+A lot of other examples can be found in RoarAudio's sources in the roarclients directory.
+
+This tutorial will cover some basics of the so called VS API.
+The VS API is a abstract layer ontop of the normal API. It is designed to be simple
+yet powerful. The VS API is all you need for most applications. If you need
+more control over what you do you must use the normal. If you need only
+a little of those extra power you can mix VS API and normal API.
+
+.SH "PLAYING A FILE"
+Playing back a file is a easy task with libroar. The VS API has some special support to play
+back files in a very simple way. This is shown here.
+
+First of all we need to include the needed header files:
+ #include <roaraudio.h>  /* libroar */
+
+This main header already includes all we need to use the VS API.
+
+Now we can start our main(). We need to declare a object for the
+VS API as it is object oriented. This object is used to interact with the server
+and send all audio data to it:
+ roar_vs_t * vss;
+ int err; /* see later */
+
+Next we need to open the connection to the server. The most simple function
+to do this is \fBroar_vs_new_from_file\fR(3) if we are going to play a file.
+It takes the folloing arguments:
+.TP
+\fBserver address\fR
+This is the address of the server. In general case This should be set to NULL.
+
+.TP
+\fBprogram name\fR
+This is the name of our program. This should be set to some name the user
+will recognize like "some App", "some Game". It \fBshould not\fR contain the filename
+of the process like "/usr/bin/someapp.bin".
+
+.TP
+\fBfile name\fR
+This is the name of the file we want to play. In fact this is a URL.
+VS API uses so called DSTR API to open files. DSTR API supports local files as well as
+for example HTTP. Examples include: "somefile.ogg", "file:///data/bla.wav",
+"http://radiostation.org:8000/bla.ogg".
+
+.TP
+\fBerror var\fR
+This is a pointer to a int used to store the error value in case of error.
+This can be set to NULL but should not. The function \fBroar_vs_strerr\fR(3)
+can be used to get a lion readable string of the error.
+
+.P
+Our call to \fBroar_vs_new_from_file\fR(3) will look like this:
+ vss = roar_vs_new_from_file(NULL, "some App", "somefile.ogg", &err);
+ if ( vss == NULL ) {
+  roar_vio_printf(roar_stderr, "Error: Can not connect to server: %s\n", roar_vs_strerr(err));
+  return 1;
+ }
+
+Next we need to continuously feed in the data so the server can do the playback.
+Again most simple way is to use \fBroar_vs_run\fR(3).
+
+ if ( roar_vs_run(vss, &err) == -1 ) {
+  roar_vio_printf(roar_stderr, "Error: can not loop: %s\n", roar_vs_strerr(err));
+ }
+
+This will block untill all of the file is played.
+
+After it returned must close the VS object. This should be done directly
+after \fBroar_vs_run\fR(3) returned. This is done this way:
+ if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == -1 ) {
+  roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err));
+  return 1;
+ }
+
+After adding some standard main() construct we should have something like this:
+ //vsfile.c:
+
+ #include <roaraudio.h>
+
+ int main (void) {
+  roar_vs_t * vss;
+  int err; /* see later */
+
+  vss = roar_vs_new_from_file(NULL, "some App", "somefile.ogg", &err);
+  if ( vss == NULL ) {
+   roar_vio_printf(roar_stderr, "Error: Can not connect to server: %s\n", roar_vs_strerr(err));
+   return 1;
+  }
+
+  if ( roar_vs_run(vss, &err) == -1 ) {
+   roar_vio_printf(roar_stderr, "Error: can not loop: %s\n", roar_vs_strerr(err));
+  }
+
+  if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == -1 ) {
+   roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err));
+   return 1;
+  }
+
+  return 0;
+ }
+
+ //ll
+
+To compile and link we can use a command like this one:
+ cc \-o vsfile vsfile.c `roar\-config \-\-libs \-\-cflags`
+
+The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libroar.
 
 .SH "PLAYING A SINE"
-First of all we need the correct header files to be included:
+Now we want to write a application playing a sine for some secs.
+We start the same way by including the correct header files:
  #include <math.h>       /* sin() */
- #include <stdio.h>      /* *printf*() */
  #include <roaraudio.h>  /* libroar */
 
 After that we need some basic varibales with data about the audio we want to play back:
  int rate     = ROAR_RATE_DEFAULT;
- int bits     = 8;
- int channels = 1; /* mono */
+ int bits     = 16;
+ int channels =  1; /* mono */
 
 Next we need to set the 'codec'. The codec is how the data is encoded.
@@ -37 +142 @@
  float length = 5; /* 5 sec */
 
-The final thing we need is a socket to send data to the demon, a buffer to store the audio data and
-a varibale to go thru the array:
- int fh;
+Next we need the buffer to hold the data as well as a varible used to go thru the buffer
+on generation of data.
+ int16_t out[1024];
  int i;
- char out[1024];
-
-To open the connection we use the call \fBroar_simple_play\fR(3):
- if ( (fh = roar_simple_play(rate, channels, bits, codec, NULL, "sine gen")) == \-1 ) {
-  fprintf(stderr, "Error: can not open playback!\\n");
-  exit(1);
+
+last we need the VS object again as well as our error var:
+ roar_vs_t * vss;
+ int err;
+
+This time we open the connection to the server using \fBroar_vs_new_playback\fR(3).
+It is similar to \fBroar_vs_new_from_file\fR(3) but takes some other options:
+.TP
+\fBserver address\fR
+Same as above.
+
+.TP
+\fBprogram name\fR
+same as above.
+
+.TP
+\fBsample rate\fR
+The number of audio frames per sec.
+
+.TP
+\fBchannels\fR
+The number of samples (one per channel) per audio frame.
+
+.TP
+\fBcodec\fR
+The codec to be used. This is one of ROAR_CODEC_*.
+In our case we use ROAR_CODEC_DEFAULT which is signed PCM in CPU native format.
+
+.TP
+\fBbits\fR
+The number of bits per sample.
+
+.TP
+\fBerror var\fR
+same as above.
+
+.P
+The call looks like this:
+ vss = roar_vs_new_playback(NULL, "vssin", rate, channels, codec, bits, &err);
+ if ( vss == NULL ) {
+  roar_vio_printf(roar_stderr, "Error: Can not connect to server: %s\n", roar_vs_strerr(err));
+  return 1;
  }
 
@@ -54 +195 @@
 
 In this loop we need to calculate our samples:
-  for (i = 0; i < 1024; i++) {
-   out[i] = 127*sin(t);
+  for (i = 0; i < (sizeof(out)/sizeof(*out)); i++) {
+   out[i] = 32767.f*sin(t);
    t += step;
   }
 
-The sine is multiplyed by 127 as our amplitude range for 8 bit signed int is from \-128 to +127.
+The sine is multiplyed by 32767 as our amplitude range for 16 bit signed int is from \-32768 to +32767.
 
 After we have our current data in \fBout\fR we want to write them to the server:
-  write(fh, out, 1024);
-
-\fBNOTE:\fR In a real application you may want to check the return value but in our simple application
-we should get \fBSIGPIPE\fR on error and simply die.
-
-After we are finished with our main loop we have to close the socket to the server.
-This is done by \fBroar_simple_close\fR(3):
- roar_simple_close(fh);
+  if ( roar_vs_write(vss, out, sizeof(out), &err) == -1 ) {
+   roar_vio_printf(roar_stderr, "Error: Can not write audio data to server: %s\n", roar_vs_strerr(err));
+   break;
+  }
+
+\fBNOTE:\fR In a real application you may want to check the return value for short writes:
+Those are writes shorter than the requested amount of data to be written. If you got any short writes
+you should try to rewrite the rest of your buffer later. This is not a error case.
+
+After we are finished with our main loop we have to close the connection to the server.
+This is done by \fBroar_vs_close\fR(3) as we already done in the file playback example:
+ if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == -1 ) {
+  roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err));
+  return 1;
+ }
 
 After adding some standard main() construct we should have something like this:
- #include <math.h>       /* sin() */
- #include <stdio.h>      /* *printf*() */
- #include <roaraudio.h>  /* libroar */
+ //vssin.c:
+
+ #include <roaraudio.h>
+ #include <math.h>
 
  int main (void) {
+  roar_vs_t * vss;
   int rate     = ROAR_RATE_DEFAULT;
-  int bits     = 8;
-  int channels = 1; /* mono */
+  int bits     = 16;
+  int channels =  1; /* mono */
   int codec    = ROAR_CODEC_DEFAULT;
-  float freq   = 523.2;            /* middle C */
-  float step   = M_PI*2*freq/rate; /* how much time per sample we have to encode ... */
+  float freq = 523.2;            /* middle C */
+  float step = M_PI*2*freq/rate; /* how much time per sample we have to encode ... */
   float t      = 0; /* current time */
   float length = 5; /* 5 sec */
-  int fh;
-  int i;
-  char out[1024];
-
-  if ( (fh = roar_simple_play(rate, channels, bits, codec, NULL, "sine gen")) == \-1 ) {
-   fprintf(stderr, "Error: can not open playback!\\n");
-   exit(1);
+  int16_t out[1024];
+  size_t i;
+  int err;
+
+  vss = roar_vs_new_playback(NULL, "vssin", rate, channels, codec, bits, &err);
+  if ( vss == NULL ) {
+   roar_vio_printf(roar_stderr, "Error: Can not connect to server: %s\n", roar_vs_strerr(err));
+   return 1;
   }
 
   while (t < 2*M_PI*freq*length) {
-   for (i = 0; i < 1024; i++) {
-    out[i] = 127*sin(t);
+   for (i = 0; i < (sizeof(out)/sizeof(*out)); i++) {
+    out[i] = 32768.f*sin(t);
     t += step;
    }
-   write(fh, out, 1024);
-  }
-
-  roar_simple_close(fh);
+
+   if ( roar_vs_write(vss, out, sizeof(out), &err) == -1 ) {
+    roar_vio_printf(roar_stderr, "Error: Can not write audio data to server: %s\n", roar_vs_strerr(err));
+    break;
+   }
+  }
+
+  if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == -1 ) {
+   roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err));
+   return 1;
+  }
 
   return 0;
  }
 
+ //ll
+
 To compile and link we can use a command like this one:
- cc \-o roarsin roarsin.c \-lm `roar\-config \-\-libs \-\-cflags`
+ cc \-o vssin vssin.c \-lm `roar\-config \-\-libs \-\-cflags`
 
 We need to use \fB-lm\fR to link the math library for \fBsin()\fR.
-The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libraor.
-
-Now we should have a working binary \fBroarsin\fR playing a sin() for 5 sec.
+The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libroar.
+
+Now we should have a working binary \fBvssin\fR playing a sin() for 5 sec.
 
 Happy hacking!