Index: doc/man3/roar_vs_buffer.3
===================================================================
--- doc/man3/roar_vs_buffer.3	(revision 5057)
+++ doc/man3/roar_vs_buffer.3	(revision 5058)
@@ -1,3 +1,3 @@
-.TH "roar_vs_buffer" "3" "May 2011" "RoarAudio" "RoarAudio Programmer's Manual"
+.TH "roar_vs_buffer" "3" "June 2011" "RoarAudio" "RoarAudio Programmer's Manual"
 
 .SH NAME
Index: doc/man3/roar_vs_file.3
===================================================================
--- doc/man3/roar_vs_file.3	(revision 5058)
+++ doc/man3/roar_vs_file.3	(revision 5058)
@@ -0,0 +1,94 @@
+.TH "roar_vs_file" "3" "June 2011" "RoarAudio" "RoarAudio Programmer's Manual"
+
+.SH NAME
+roar_vs_file, roar_vs_file_simple, roar_vs_new_from_file \- File mode for VS API
+
+.SH SYNOPSIS
+
+#include <roaraudio.h>
+
+int roar_vs_file(roar_vs_t * vss, struct roar_vio_calls * vio, int closefile, int * error);
+
+int roar_vs_file_simple(roar_vs_t * vss, char * filename, int * error);
+
+roar_vs_t * roar_vs_new_from_file(const char * server, const char * name, char * filename, int * error);
+
+.SH "DESCRIPTION"
+These functions are used to open the VS object in file mode. In the file mode the VS API
+reads or writes the data from or to the file itself. The file mode uses normal VIO/DSTR so
+it supports streams as well. Just pass the stream URL as filename.
+
+\fBroar_vs_file()\fR sets up the file mode for a already opened object using the open VIO handle \fBvio\fR.
+This function requires the use of \fBroar_vs_stream\fR(3).
+
+\fBroar_vs_file_simple()\fR sets up the file mode using a given filename (or URL). It opens the file using DSTR
+API. By default the function assumes playback mode and tries to auto detect the audio parameters.
+To override the auto detection or use a diffrent stream direction use \fBroar_vs_stream\fR(3).
+
+\fBroar_vs_new_from_file()\fR creates a new VS object and enters file mode using the file (or URL) given as
+\fBfilename\fR.
+
+To send data to or read data from use \fBroar_vs_iterate\fR(3) or \fBroar_vs_run\fR(3).
+
+.SH "PARAMETERS"
+.TP
+\fBserver\fR
+The server to connect to. NULL for defaults.
+
+.TP
+\fBname\fR
+The application name. This should be something the user can use to identify the application.
+It MUST NOT be the application's binary name or the value of argv[0].
+
+.TP
+\fBvio\fR
+The VIO handle to be used by the file mode.
+
+.TP
+\fBclosefile\fR
+This parameter tells the file mode if the file should be closed on roar_vio_close(3).
+Must be ROAR_VS_TRUE (common) or ROAR_VS_FALSE.
+
+.TP
+\fBfilename\fR
+The filename used to open the file for file mode. The file is opend using DSTR API.
+All kinds of files supported by DSTR are supported. This includes HTTP streams.
+
+.TP
+\fBerror\fR
+This is a pointer to a integer used to store the error value in case of error.
+This can be NULL if not used but it is very recommended to use this error value to report
+good error messages to the user.
+
+.SH "RETURN VALUE"
+On success roar_vs_new_from_file() return a new VS object.  On error, NULL is returned.
+roar_vs_file() and roar_vs_file_simple() returns 0 on success and \-1 on error.
+
+
+.SH "EXAMPLES"
+ roar_vs_t * vss;
+ int err;
+
+ vss = roar_vs_new_from_file(NULL, "MyApp", "http://...", &err);
+ if ( vss == NULL ) {
+  //handle error.
+ }
+
+ if ( roar_vs_run(vss, &err) == -1 ) {
+  //handle error.
+ }
+
+ if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == -1 ) {
+  //handle error.
+ }
+
+.SH "SEE ALSO"
+\fBroar_vs_new_simple\fR(3),
+\fBroar_vs_iterate\fR(3),
+\fBroar_vs_run\fR(3),
+\fBroar_vs_close\fR(3),
+\fBroarvs\fR(7),
+\fBlibroar\fR(7),
+\fBRoarAudio\fR(7).
+
+.\" ll
Index: doc/man3/roar_vs_new.3
===================================================================
--- doc/man3/roar_vs_new.3	(revision 5058)
+++ doc/man3/roar_vs_new.3	(revision 5058)
@@ -0,0 +1,62 @@
+.TH "roar_vs_new" "3" "June 2011" "RoarAudio" "RoarAudio Programmer's Manual"
+
+.SH NAME
+roar_vs_stream, roar_vs_new_from_con \- Create new VS objects
+
+.SH SYNOPSIS
+
+#include <roaraudio.h>
+
+roar_vs_t * roar_vs_new(const char * server, const char * name, int * error);
+
+roar_vs_t * roar_vs_new_from_con(struct roar_connection * con, int * error);
+
+.SH "DESCRIPTION"
+These calls are used to create new VS objects without a yet connected data connection.
+They are only helpful if there you want to share a control connection between multiple streams
+(generally recommended if using multiple streams to the same server) or need to use some
+extended parts of the VS API. If you look for a easy way to open a stream see
+\fBroar_vs_new_simple\fR(3) and \fBroar_vs_new_from_file\fR(3).
+
+\fBroar_vs_new()\fR opens a new control connection to server \fBserver\fR.
+\fBname\fR is used as application name.
+
+\fBroar_vs_new_from_con()\fR creates a new VS object from the extsing control connection \fBcon\fR.
+
+VS objects created via roar_vs_new_from_con() will not close the control connection on roar_vs_close(3).
+
+.SH "PARAMETERS"
+.TP
+\fBserver\fR
+The server to connect to. NULL for defaults.
+
+.TP
+\fBname\fR
+The application name. This should be something the user can use to identify the application.
+It MUST NOT be the application's binary name or the value of argv[0].
+
+.TP
+\fBcon\fR
+The already existing and open control connection to use.
+
+.TP
+\fBerror\fR
+This is a pointer to a integer used to store the error value in case of error.
+This can be NULL if not used but it is very recommended to use this error value to report
+good error messages to the user.
+
+.SH "RETURN VALUE"
+On success these calls return a new VS object.  On error, NULL is returned.
+
+.SH "EXAMPLES"
+FIXME
+
+.SH "SEE ALSO"
+\fBroar_vs_new_simple\fR(3),
+\fBroar_vs_new_from_file\fR(3),
+\fBroar_vs_close\fR(3),
+\fBroarvs\fR(7),
+\fBlibroar\fR(7),
+\fBRoarAudio\fR(7).
+
+.\" ll
Index: doc/man3/roar_vs_new_simple.3
===================================================================
--- doc/man3/roar_vs_new_simple.3	(revision 5058)
+++ doc/man3/roar_vs_new_simple.3	(revision 5058)
@@ -0,0 +1,64 @@
+.TH "roar_vs_new_simple" "3" "June 2011" "RoarAudio" "RoarAudio Programmer's Manual"
+
+.SH NAME
+roar_vs_new_simple, roar_vs_new_playback \- Create new VS objects
+
+.SH SYNOPSIS
+
+#include <roaraudio.h>
+
+roar_vs_t * roar_vs_new_simple(const char * server, const char * name, int rate, int channels, int codec, int bits, int dir, int * error);
+
+roar_vs_t * roar_vs_new_playback(const char * server, const char * name, int rate, int channels, int codec, int bits, int * error);
+
+.SH "DESCRIPTION"
+These functions create a new VS object with a already connected data connection.
+The functions connect to the server \fBserver\fR with application name \fBname\fR.
+They take the audio parameters as arguments \fBrate\fR, \fBchannels\fR, \fBcodec\fR, \fBbits\fR.
+
+\fBroar_vs_new_simple()\fR takes the stream direction as parameter \fBdir\fR.
+
+\fBroar_vs_new_playback()\fR is equivalent to roar_vs_new_simple() expect that it does not take the direction parameter but uses ROAR_DIR_PLAY (waveform playback). It may be implemented as a macro.
+
+.SH "PARAMETERS"
+.TP
+\fBserver\fR
+The server to connect to. NULL for defaults.
+
+.TP
+\fBname\fR
+The application name. This should be something the user can use to identify the application.
+It MUST NOT be the application's binary name or the value of argv[0].
+
+.TP
+\fBrate\fR, \fBchannels\fR, \fBcodec\fR, \fBbits\fR
+The audio parameters for the new stream: sampling rate, number of channels per frame,
+used codec and number of bits per sample.
+
+.TP
+\fBdir\fR
+This is the stream direction. Common values include ROAR_DIR_PLAY for waveform playback,
+ROAR_DIR_MONITOR for waveform monitoring, ROAR_DIR_RECORD for waveform recording.
+For MIDI ROAR_DIR_MIDI_IN and ROAR_DIR_MIDI_OUT is used.
+
+.TP
+\fBerror\fR
+This is a pointer to a integer used to store the error value in case of error.
+This can be NULL if not used but it is very recommended to use this error value to report
+good error messages to the user.
+
+.SH "RETURN VALUE"
+On success these calls return a new VS object.  On error, NULL is returned.
+
+.SH "EXAMPLES"
+FIXME
+
+.SH "SEE ALSO"
+\fBroar_vs_new\fR(3),
+\fBroar_vs_new_from_file\fR(3),
+\fBroar_vs_close\fR(3),
+\fBroarvs\fR(7),
+\fBlibroar\fR(7),
+\fBRoarAudio\fR(7).
+
+.\" ll
Index: doc/man3/roar_vs_position.3
===================================================================
--- doc/man3/roar_vs_position.3	(revision 5058)
+++ doc/man3/roar_vs_position.3	(revision 5058)
@@ -0,0 +1,62 @@
+.TH "roar_vs_position" "3" "June 2011" "RoarAudio" "RoarAudio Programmer's Manual"
+
+.SH NAME
+roar_vs_position, roar_vs_latency \- Get stream position information
+
+.SH SYNOPSIS
+
+#include <roaraudio.h>
+
+ssize_t roar_vs_position(roar_vs_t * vss, int backend, int * error);
+
+roar_mus_t roar_vs_latency(roar_vs_t * vss, int backend, int * error);
+
+.SH "DESCRIPTION"
+\fBroar_vs_position()\fR returns the current server site position of the stream plus
+the current offset for the selected backend.
+
+\fBroar_vs_latency()\fR returns the latency between the client site stream position and the server
+site position plus the latency by the backend.
+
+Use of roar_vs_latency() is not recommended as it requires the codec to use a true constant bit rate.
+
+Calling these functions too often will result in bad performance and incorrect data
+(pool interval smaller than server response time). Polling up to 20 times per second shoudn't be a problem.
+
+.SH "PARAMETERS"
+.TP
+\fBvss\fR
+The VS object to be used.
+
+.TP
+\fBbackend\fR
+The backend used for correction. This can be a stream ID of the stream to use as backend or one of the special values
+defined by the constants ROAR_VS_BACKEND_*.
+ROAR_VS_BACKEND_NONE is used to ask for no correction.
+ROAR_VS_BACKEND_DEFAULT is used to ask for the default correction. This should be used in all common cases.
+ROAR_VS_BACKEND_FIRST is used to ask for correction based on the first primary stream on the same mixer.
+
+.TP
+\fBerror\fR
+This is a pointer to a integer used to store the error value in case of error.
+This can be NULL if not used but it is very recommended to use this error value to report
+good error messages to the user.
+
+.SH "RETURN VALUE"
+roar_vs_position() returns the stream position on success and \-1 on error.
+Stream position is the current position of the stream in units of samples (not frames!).
+
+roar_vs_latency() returns the stream latency on success and zero on error. However zero is a valid
+value. In case of error \fBerror\fR is set to the error. In case of no error but zero latency
+\fBerror\fR is cleared (set to ROAR_ERROR_NONE).
+Latency is retruned in mu-seconds (1/10^-6s).
+
+.SH "EXAMPLES"
+FIXME
+
+.SH "SEE ALSO"
+\fBroarvs\fR(7),
+\fBlibroar\fR(7),
+\fBRoarAudio\fR(7).
+
+.\" ll
Index: doc/man3/roar_vs_stream.3
===================================================================
--- doc/man3/roar_vs_stream.3	(revision 5058)
+++ doc/man3/roar_vs_stream.3	(revision 5058)
@@ -0,0 +1,72 @@
+.TH "roar_vs_stream" "3" "June 2011" "RoarAudio" "RoarAudio Programmer's Manual"
+
+.SH NAME
+roar_vs_stream \- Set up stream parameters for VS object
+
+.SH SYNOPSIS
+
+#include <roaraudio.h>
+
+int roar_vs_stream(roar_vs_t * vss, const struct roar_audio_info * info, int dir, int * error);
+
+.SH "DESCRIPTION"
+This function asks a VS object opened by \fBroar_vs_new_from_con\fR(3) or \fBroar_vs_new\fR(3)
+to open the data connection using the audio parameters \fBinfo\fR and the stream direction \fBdir\fR.
+
+This function needs to be called before data is read or written if one of the above functions is used
+to create the VS object.
+
+This function is also used to provide parameters for the file mode
+(which is started by using \fBroar_vs_file\fR(3) or \fBroar_vs_file_simple\fR(3)).
+To play back a file this is not needed in a common case as the VS API tries to find correct parameters.
+It is required for all other stream directions. See \fBroar_vs_file\fR(3) and \fBroar_vs_file_simple\fR(3)
+for more information.
+
+On failture this function can be called again with diffrent parameters.
+
+.SH "PARAMETERS"
+.TP
+\fBvss\fR
+The VS object to be updated.
+
+.TP
+\fBinfo\fR
+This is a pointer to the roar_audio_info structure storing the audio format parameters.
+The structure contains the following memebers:
+rate (sample rate), bits (bits per sample), channels (channels per frame) and codec.
+
+.TP
+\fBdir\fR
+This is the stream direction. Common values include ROAR_DIR_PLAY for waveform playback,
+ROAR_DIR_MONITOR for waveform monitoring, ROAR_DIR_RECORD for waveform recording.
+For MIDI ROAR_DIR_MIDI_IN and ROAR_DIR_MIDI_OUT is used.
+
+.TP
+\fBerror\fR
+This is a pointer to a integer used to store the error value in case of error.
+This can be NULL if not used but it is very recommended to use this error value to report
+good error messages to the user.
+
+.SH "RETURN VALUE"
+On success these calls return 0.  On error, \-1 is returned.
+
+.SH "EXAMPLES"
+ struct roar_audio_info info;
+ int err;
+
+ if ( roar_profile2info(&info, "isdn-eu") == -1 ) {
+  // error handling.
+ }
+
+ if ( roar_vs_stream(vss, &info, ROAR_DIR_PLAY, &err) == -1 ) {
+  // error handling.
+ }
+
+.SH "SEE ALSO"
+\fBroar_vs_file\fR(3),
+\fBroar_vs_file_simple\fR(3),
+\fBroarvs\fR(7),
+\fBlibroar\fR(7),
+\fBRoarAudio\fR(7).
+
+.\" ll
Index: doc/man7/RoarAudio.7
===================================================================
--- doc/man7/RoarAudio.7	(revision 4613)
+++ doc/man7/RoarAudio.7	(revision 5058)
@@ -34,11 +34,8 @@
 \fBroar-config\fR(1),
 \fBroarcat\fR(1),
-\fBroarcat2sock\fR(1),
-\fBroarcatad\fR(1),
 \fBroarctl\fR(1),
 \fBroarfilt\fR(1),
 \fBroarfish\fR(1),
 \fBroarmon\fR(1),
-\fBroarsockconnect\fR(1),
 \fBroartypes\fR(1),
 \fBroarvorbis\fR(1),
Index: doc/man7/libroar.7
===================================================================
--- doc/man7/libroar.7	(revision 4613)
+++ doc/man7/libroar.7	(revision 5058)
@@ -1,4 +1,4 @@
 .\" RoarAudio
-.TH "libroar" "7" "November 2010" "RoarAudio" "System Manager's Manual: RoarAuido"
+.TH "libroar" "7" "June 2011" "RoarAudio" "System Manager's Manual: RoarAuido"
 
 .SH NAME
@@ -10,6 +10,6 @@
 
 .SH "DESCRIPTION"
-\fBlibroar\fR is the central library used to comunicate with RoarAudio servers.
-It suppots all commands from simple commands to play some audio up to complex commands
+\fBlibroar\fR is a central library used to comunicate with RoarAudio servers.
+It supports all commands from simple commands to play some audio up to complex commands
 to controll the server and do nice things over the network.
 It also includes several useful functions from buffer mangement to IO abstraction.
@@ -20,4 +20,6 @@
 You may start by looking at \fBroarcat\fR(1)s source code as an example on how to simply play back
 some audio. A more complex example is \fBroarvorbis\fR(1) which also includes meta data updates.
+
+You should also have a look at VS API, see \fBroarvs\fR(7) for a overview.
 
 .SH "TUTORIALS"
@@ -81,4 +83,5 @@
 \fBroar-config\fR(1),
 \fBroartypes\fR(1),
+\fBroarvs\fR(7),
 \fBroartut\fR(7),
 \fBroard\fR(1),
@@ -87,5 +90,5 @@
 
 .SH "HISTORY"
-Project started in mid of 2008.
+See \fBRoarAudio\fR(7).
 
 .\"ll
Index: doc/man7/roarvs.7
===================================================================
--- doc/man7/roarvs.7	(revision 5058)
+++ doc/man7/roarvs.7	(revision 5058)
@@ -0,0 +1,82 @@
+.\" RoarAudio
+.TH "roarvs" "7" "June 2011" "RoarAudio" "System Manager's Manual: RoarAuido"
+
+.SH NAME
+libroar \- RoarAudio sound library
+
+roarvs \- RoarAudio very simple API
+
+.SH SYNOPSIS
+
+ #include <roaraudio.h>
+
+ roar_vs_t * vss;
+
+.SH "DESCRIPTION"
+The VS (for Very Simple) API is a high level abstraction layer used to allow use of RoarAudio
+from very simple programs. The API was designed to help people to easly upgrade existing artsc and pulse-simple
+code to RoarAudio. While the API is equivalently simple it is much more powerful than one one by
+aRtsc or PulseAudio.
+
+The VS API also has a mode to play back (and record) files easly. As this uses VIO/DSTR it can handle
+streams as well.
+
+.\".SH "EXAMPLES"
+
+.SH "TUTORIALS"
+Tutorials can be found in \fBroartut\fR(7).
+
+.SH "IMPORTANT FUNCTIONS"
+There are several important functions. This is a small list of the most important ones.
+
+.TP
+\fBError handlingf\fR
+\fBroar_vs_strerr\fR(3)
+
+.TP
+\fBOpening\fR
+\fBroar_vs_new\fR(3), \fBroar_vs_new_simple\fR(3), \fBroar_vs_new_playback\fR(3),
+\fBroar_vs_new_from_file\fR(3)
+
+.TP
+\fBClosing\fR
+\fBroar_vs_close\fR(3)
+
+.TP
+\fBReading and writing\fR
+\fBroar_vs_read\fR(3), \fBroar_vs_write\fR(3)
+
+.TP
+\fBNon-Blocking and Asyncron IO\fR
+\fBroar_vs_blocking\fR(3),
+\fBroar_vio_select\fR(3)
+
+.TP
+\fBVolume and Flags\fR
+\fBroar_vs_pause\fR(3), \fBroar_vs_mute\fR(3),
+\fBroar_vs_volume_mono\fR(3), \fBroar_vs_volume_stereo\fR(3), \fBroar_vs_volume_get\fR(3)
+
+.TP
+\fBMeta data\fR
+\fBroar_vs_meta\fR(3), \fBroar_vs_role\fR(3)
+
+.TP
+\fBFile mode\fR
+\fBroar_vs_file\fR(3), \fBroar_vs_file_simple\fR(3),
+\fBroar_vs_iterate\fR(3), \fBroar_vs_run\fR(3)
+
+.TP
+\fBBuffered mode\fR
+\fBroar_vs_buffer\fR(3),
+\fBroar_vs_iterate\fR(3), \fBroar_vs_run\fR(3)
+
+.SH "BUGS"
+A lot...
+
+.SH "SEE ALSO"
+\fBroar-config\fR(1),
+\fBroartypes\fR(1),
+\fBroartut\fR(7),
+\fBRoarAudio\fR(7).
+
+.\"ll
Index: doc/symlinks.src
===================================================================
--- doc/symlinks.src	(revision 5057)
+++ doc/symlinks.src	(revision 5058)
@@ -23,2 +23,7 @@
 roar_vs_get_avail_write		3	roar_vs_buffer		3
 roar_vs_reset_buffer		3	roar_vs_buffer		3
+roar_vs_new_from_con		3	roar_vs_new		3
+roar_vs_new_playback		3	roar_vs_new_simple	3
+roar_vs_file_simple		3	roar_vs_stream		3
+roar_vs_new_from_file		3	roar_vs_stream		3
+roar_vs_latency			3	roar_vs_position	3
