AFSEEKFRAME(3)

✨ AFSEEKFRAME(3) ✨

okay bestie, welcome to the Audio File Library manual, section 3 💖 this one's about afSeekFrame and afTellFrame, which are literally the vibe-check functions for where am I in this audio track rn 🎀

🦋 NAME 🦋

afSeekFrame, afTellFrame — update or access the current sample frame position for a track in an audio file

no cap, that's the whole thing. one moves you, one tells you where you are. iconic duo behavior fr fr 💅

🌸 SYNOPSIS 🌸

#include <audiofile.h>

AFframecount afSeekFrame(AFfilehandle file, int track,
    AFframecount frameOffset);

AFframecount afTellFrame(AFfilehandle file, int track);

yes, you do need that #include <audiofile.h>, don't skip it 🙈

🎀 PARAMETERS 🎀

• file — bestie this has to be a valid audio file handle, the kind you got from afOpenFile(3). no random ints, we're not doing that today 💀
• track — tells us which audio track inside the file we're talking about. and listen: track is always AF_DEFAULT_TRACK for all currently supported audio file formats. that's it, that's the whole menu 🍓
• frameOffset — a sample frame offset. valid ones have to be greater than or equal to zero and strictly less than the number of sample frames in the specified audio track. so like, zero is fine, the last frame is fine, but the count itself? not fine. and the special value -1 is also allowed, which we'll get into 👑

✨ DESCRIPTION ✨

afSeekFrame moves the logical file position for a specified audio track to a desired sample frame location. it's giving teleportation but for audio files 🧚

but here's the fun part: if frameOffset is -1, afSeekFrame will not modify the current file offset and will instead return the current file position. so -1 is like... the "actually never mind, where was I?" option 💅

afTellFrame returns the current file position in sample frames. that's it. that's the function. it just tells you. main character energy, honestly 🌈

🔥 RETURN VALUE 🔥

on success, afSeekFrame and afTellFrame will return the current file position as measured in sample frames from the start of the audio track ⭐

on failure, afSeekFrame and afTellFrame will return the value -1 😭

ok so heads up: -1 is BOTH a valid frameOffset argument AND the failure return value. do not let that trip you up bestie, check your errors 💀

💜 ERRORS 💜

the following errors can be generated by afSeekFrame or afTellFrame:

• AF_BAD_FILEHANDLE — file does not represent a valid file handle. (your handle is fake, girl, we can't work with this 🚫)
• AF_BAD_TRACK — track does not identify a valid track. 👀
• AF_BAD_LSEEK — a call to lseek failed. the underlying seek said nope 🙈

👑 AUTHOR 👑

Michael Pruett <michael@68k.org>

we stan 🫶

and that's the whole page bestie!! this was the AFSEEKFRAME(3) entry from the Audio File Library 0.3.6 man pages, dated 03/06/2013. go forth and seek responsibly 💖✨🎀