NAME

       roar_vs_position, roar_vs_latency, roar_vs_latency2 - Get stream position information

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);

       roar_mus_t roar_vs_latency2(roar_vs_t * vss, int backend, int wait, int * error);

DESCRIPTION

       roar_vs_position() returns the current server site position of the stream plus the current
       offset for the selected backend.

       roar_vs_latency() 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.

       roar_vs_latency2() is perfectly equivalent to roar_vs_latency() expect that it  takes  the
       additional   parameter  wait.  The  wait  parameter  may  have  the  values  ROAR_VS_WAIT,
       ROAR_VS_NOWAIT and ROAR_VS_ASYNC.  If it is ROAR_VS_WAIT the function  does  the  same  as
       roar_vs_latency().   If  the  parameter  is  ROAR_VS_NOWAIT roar_vs_latency2() will return
       interpolated  data  based  on  old  data  collected   by   calls   to   roar_vs_latency(),
       roar_vs_latency2()  or  roar_vs_position().   ROAR_VS_ASYNC  is  used  to trigger asyncron
       updates to this internal state. Asyncron operations need to be enabled before they can  be
       used. See roar_vs_ctl(3).

       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.

PARAMETERS

       vss    The VS object to be used.

       backend
              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.

       wait   Tells the API if the call should wait or not. Must be ROAR_VS_WAIT,  ROAR_VS_NOWAIT
              or ROAR_VS_ASYNC.

       error  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.

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 error is set to the error. In case of no error but zero
       latency error is cleared (set to ROAR_ERROR_NONE).   Latency  is  retruned  in  mu-seconds
       (1/10^-6s).

EXAMPLES

       FIXME

SEE ALSO

       roarvs(7), libroar(7), RoarAudio(7).