roar_vs_position(3)

💖 roar_vs_position(3) — the RoarAudio Programmer's Manual, but make it cute 💖

okay bestie, sit down, hydrate, and let me tell you about three functions that tell you where your stream is at. literally. like, positionally. it's in the RoarAudio Programmer's Manual and it's lowkey iconic. 🎀

---

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

like yes, three of them, all holding hands. 💅

---

✨ DESCRIPTION ✨

so. roar_vs_position() hands you the current server site position of the stream, plus the current offset for whichever backend you picked. that's it. that's the vibe. ✨

roar_vs_latency() gives you the latency between the client site stream position and the server site position — plus the latency added by the backend.

🚨 bestie, listen. using roar_vs_latency() is not recommended. why? because it requires the codec to use a true constant bit rate. no cap. if that's not your codec's whole deal, this function is not your friend. 💀

roar_vs_latency2() is perfectly equivalent to roar_vs_latency() — except it takes the extra parameter wait. and wait is a whole personality:

• if wait is ROAR_VS_WAIT, the function does exactly the same thing as roar_vs_latency() 🫶
• if wait is ROAR_VS_NOWAIT, then roar_vs_latency2() returns interpolated data based on old data collected by calls to roar_vs_latency(), roar_vs_latency2() or roar_vs_position(). yes, it's reusing the receipts from earlier calls. 🧚
• ROAR_VS_ASYNC is used to trigger asyncron updates to this internal state. and heads up: asyncron operations need to be enabled before they can be used. see roar_vs_ctl(3). 🔥

and now the part nobody wants to hear: calling these functions too often will result in bad performance and incorrect data (that's when your pool interval is smaller than the server response time 😭). the good news? polling up to 20 times per second shoudn't be a problem. so chill, you don't need to spam it. 🍓

---

✨ PARAMETERS ✨

• vss — the VS object you're using. your main character. 👑
• 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 — used to ask for no correction 🙈
  • ROAR_VS_BACKEND_DEFAULT — used to ask for the default correction. this should be used in all common cases. like, default to this, fr fr. 🫶
  • ROAR_VS_BACKEND_FIRST — 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 — 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 so you can report good error messages to the user. bestie, please use it. your users deserve nice errors. 💖

---

✨ RETURN VALUE ✨

roar_vs_position() returns the stream position on success and -1 on error. and stream position is the current position of the stream in units of samples (not frames!). not frames. NOT frames. 🫠

roar_vs_latency() returns the stream latency on success and zero on error. however — plot twist — zero is a valid value. 😭 so:

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

and latency is retruned in mu-seconds (1/10^-6s). yes, mu-seconds. that's what the page says. 💅

---

✨ EXAMPLES ✨

FIXME

ngl bestie the examples are literally just FIXME 😭 iconic behaviour honestly. leaving it exactly as written, because that's the whole content of this section.

---

✨ SEE ALSO ✨

roarvs(7), libroar(7), RoarAudio(7) 🦋

---

and that's the tea, bestie — go forth and poll responsibly (max like 20 times a second, remember 🌸). this little number is from RoarAudio, dated June 2011, and it lives at roar_vs_position(3). mwah 💜🎀✨