audio_frame.h File Reference

Zero-copy audio frame container carrying one PCM or codec-encoded packet. More...

#include <cstdint>
#include <string_view>
#include "../base/bytes.h"
#include "./header.h"

Include dependency graph for audio_frame.h:

Go to the source code of this file.

Namespaces
	vlink
	vlink::zerocopy

Functions
struct	vlink::zerocopy::VLINK_EXPORT_AND_ALIGNED (8) AudioFrame final

Detailed Description

Zero-copy audio frame container carrying one PCM or codec-encoded packet.

AudioFrame is the canonical conduit for in-vehicle and embedded audio pipelines: microphone capture, in-cabin voice command, TTS playback, alarm tones, and intercom routing. Each frame carries one acquisition window of audio together with sample-format metadata (sample rate, channels, bit depth, layout, codec hint, language tag), a capture timestamp, the advertised frame duration, plus a 40-byte Header for sequencing and dual-timestamp latency measurement.

Audio formats

Enum	Encoding	Typical bit depth	Compression
kFormatPcmS16	Signed linear PCM	16	None
kFormatPcmS24	Signed linear PCM packed	24	None
kFormatPcmS32	Signed linear PCM	32	None
kFormatPcmF32	IEEE-754 float PCM	32	None
kFormatPcmU8	Unsigned linear PCM	8	None
kFormatOpus	Opus	N/A	Lossy
kFormatAac	AAC	N/A	Lossy
kFormatMp3	MP3	N/A	Lossy
kFormatFlac	FLAC	N/A	Lossless

Common sample rates: 8 kHz / 16 kHz / 32 kHz / 44.1 kHz / 48 kHz / 96 kHz. Channel layouts: kLayoutInterleaved (L R L R ...) or kLayoutPlanar (separate per-channel planes).

Wire format

AudioFrame is POD; memcpy of the struct snapshot plus the audio buffer forms the wire payload. The sizeof value is locked by static_assert and forms a permanent contract: vlink::zerocopy::* containers have NO forward and NO backward binary compatibility – every field, including reserved bytes, is part of the wire contract.

static_assert(sizeof(AudioFrame) == 128, "Sizeof must be 128 bytes.");

Memory layout

Offset  Size  Field
------  ----  --------------------------
     0    40  Header   header
    40     8  uint8_t* data_
    48     8  size_t   size_
    56     8  uint64_t update_time_ns_
    64     8  uint64_t duration_ns_
    72    16  char     codec_[16]
    88     8  char     language_[8]
    96     4  uint32_t channel_
   100     4  uint32_t freq_
   104     4  uint32_t sample_rate_
   108     4  uint32_t num_samples_
   112     4  uint32_t bitrate_
   116     2  uint16_t num_channels_
   118     2  uint16_t bit_depth_
   120     1  Format   format_
   121     1  Layout   layout_
   122     1  bool     is_owner_
   123     1  uint8_t  reserved_buf_
   124     4  uint32_t reserved_buf2_
------  ----  --------------------------
 Total   128  bytes (alignas 8)
 
Wire envelope:
[ magic_begin (4) | version (4) | AudioFrame struct (128) | audio bytes (size_) | magic_end (4) ]

Reserved bytes

reserved_buf_ and reserved_buf2_ are exposed through the get_reserved* helpers. They travel through the wire format and are deliberately preserved by clear() and the copy/move helpers. They MUST NOT be repurposed by application code: a future library revision may bind them to real fields, which would silently break peers that abused the slot.

Example

vlink::zerocopy::AudioFrame frame;
frame.set_sample_rate(48000);
frame.set_num_channels(2);
frame.set_num_samples(960);
frame.set_bit_depth(16);
frame.set_format(vlink::zerocopy::AudioFrame::kFormatPcmS16);
frame.set_layout(vlink::zerocopy::AudioFrame::kLayoutInterleaved);
frame.set_codec("PCM");
frame.create(960 * 2 * sizeof(int16_t));
 
vlink::Bytes wire;
frame >> wire;