roar_vs_file(3)

💖 roar_vs_file — the RoarAudio Programmer's Manual, but make it cute 💖

okay bestie, sit down, we're doing file mode today and honestly? it's giving main character energy. this is roar_vs_file(3) from the RoarAudio fam, and if you're here it's because you want the VS API to read from or write to a file (or a URL, we don't discriminate 💅).

---

✨ NAME ✨

roar_vs_file, roar_vs_file_simple, roar_vs_new_from_file — file mode for the VS API 🎀

---

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

---

🦋 DESCRIPTION 🦋

so these three functions are the way you open a VS object in file mode. and what is file mode, you ask? it's when the VS API literally just reads the data from the file or writes the data to the file itself. no drama, no middleman. and because file mode uses normal VIO/DSTR, it supports streams too — so yeah, you can just pass a stream URL as the filename and it will absolutely eat that up. periodt. 💅

• roar_vs_file() — sets up file mode for an object you already opened, using the open VIO handle vio. lowkey important: this one requires you to use roar_vs_stream(3).
• roar_vs_file_simple() — sets up file mode from a given filename (or URL) and opens the file with the DSTR API. by default it assumes playback mode and tries to auto detect the audio parameters. want to override that auto detection or go a different stream direction? that's a roar_vs_stream(3) job, bestie.
• roar_vs_new_from_file() — creates a brand new VS object and drops it straight into file mode using the file (or URL) you passed as filename.

and to actually send data to it or read data from it, you use roar_vs_iterate(3) or roar_vs_run(3). slay. 🫶

---

💜 PARAMETERS 💜

• server — the server to connect to. NULL for defaults. (yes, NULL is a valid vibe.)
• name — 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]. like, do not do that. 🙈
• vio — the VIO handle that file mode is gonna use.
• closefile — tells file mode whether the file should be closed on roar_vio_close(3). must be ROAR_VS_TRUE (the common one) or ROAR_VS_FALSE.
• filename — the filename used to open the file for file mode. the file is opend using the DSTR API. every kind of file DSTR supports is supported here — yes, that includes HTTP streams. 🌈
• error — a pointer to an integer that stores the error value in case of error. you can pass NULL if you're not using it, but ngl it is very recommended to use this error value so you can report good error messages to the user. your future self will thank you 💖

---

🎀 RETURN VALUE 🎀

on success, roar_vs_new_from_file() returns a shiny new VS object. ✨ on error, NULL is returned. roar_vs_file() and roar_vs_file_simple() return 0 on success and -1 on error. iconic behavior, honestly.

---

🔥 EXAMPLES 🔥

here's the whole vibe, copy it and go:

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

---

🌟 SEE ALSO 🌟

roar_vs_new_simple(3), roar_vs_iterate(3), roar_vs_run(3), roar_vs_close(3), roarvs(7), libroar(7), RoarAudio(7).

---

no cap: if you're touching name, remember it's for the user to identify the app — not your binary name, not argv[0]. that's the one rule that will get you every time. 💀

---

and that's the whole page, bestie 🫶 this one's brought to you by RoarAudio, dated June 2011 — yeah, she's vintage, she's classic, she's still slaying. mwah 💅💖