@parastud/react-native-vban 0.1.0

package/android/src/main/java/expo/modules/systemaudiocapture/VbanSenderModule.kt

@@ -0,0 +1,129 @@
+package expo.modules.systemaudiocapture
+
+import android.content.Context
+import android.content.Intent
+import android.media.AudioFormat
+import android.media.AudioRecord
+import android.media.MediaRecorder
+import android.os.Build
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * Native VBAN sender. Captures audio and streams it out as VBAN entirely in
+ * native code (no JS bridge in the hot path), so packets are evenly paced and
+ * the receiver doesn't see jitter/errors.
+ *
+ *  - Microphone: builds an AudioRecord(MIC) here and runs a VbanSendEngine.
+ *  - Device audio: delegates to SystemAudioCaptureService (foreground service +
+ *    MediaProjection), which runs its own VbanSendEngine.
+ */
+class VbanSenderModule : Module() {
+  private var engine: VbanSendEngine? = null
+  private var deviceActive = false
+
+  private val context: Context
+    get() = appContext.reactContext ?: throw Exceptions.ReactContextLost()
+
+  override fun definition() = ModuleDefinition {
+    Name("VbanNativeSender")
+    Events("onStats", "onError")
+
+    AsyncFunction("startMic") {
+      host: String, port: Int, streamName: String, sampleRate: Int, channels: Int, promise: Promise ->
+      try {
+        startMic(host, port, streamName, sampleRate, channels)
+        promise.resolve(null)
+      } catch (e: Exception) {
+        promise.reject("MIC_START_FAILED", e.message, e)
+      }
+    }
+
+    AsyncFunction("startDevice") {
+      host: String, port: Int, streamName: String, sampleRate: Int, channels: Int, promise: Promise ->
+      if (SystemAudioCaptureService.resultData == null) {
+        promise.reject("NO_PERMISSION", "Request device-capture permission first", null)
+        return@AsyncFunction
+      }
+      SystemAudioCaptureService.host = host
+      SystemAudioCaptureService.port = port
+      SystemAudioCaptureService.streamName = streamName
+      SystemAudioCaptureService.sampleRate = sampleRate
+      SystemAudioCaptureService.channels = channels
+      SystemAudioCaptureService.onStats = { level, packets ->
+        sendEvent("onStats", mapOf("level" to level, "packets" to packets))
+      }
+      SystemAudioCaptureService.onErr = { msg ->
+        sendEvent("onError", mapOf("message" to msg))
+      }
+      val intent = Intent(context, SystemAudioCaptureService::class.java).apply {
+        action = SystemAudioCaptureService.ACTION_START
+      }
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        context.startForegroundService(intent)
+      } else {
+        context.startService(intent)
+      }
+      deviceActive = true
+      promise.resolve(null)
+    }
+
+    AsyncFunction("stop") { promise: Promise ->
+      engine?.stop()
+      engine = null
+      if (deviceActive) {
+        deviceActive = false
+        SystemAudioCaptureService.onStats = null
+        SystemAudioCaptureService.onErr = null
+        val intent = Intent(context, SystemAudioCaptureService::class.java).apply {
+          action = SystemAudioCaptureService.ACTION_STOP
+        }
+        context.startService(intent)
+      }
+      promise.resolve(null)
+    }
+
+    OnDestroy {
+      engine?.stop()
+      engine = null
+    }
+  }
+
+  private fun startMic(host: String, port: Int, streamName: String, sampleRate: Int, channels: Int) {
+    engine?.stop()
+
+    val record = buildMicRecord(sampleRate, channels)
+    val actualChannels = if (record.channelCount > 0) record.channelCount else channels
+
+    engine = VbanSendEngine(
+      record, host, port, streamName, sampleRate, actualChannels,
+      onStats = { level, packets -> sendEvent("onStats", mapOf("level" to level, "packets" to packets)) },
+      onError = { msg -> sendEvent("onError", mapOf("message" to msg)) },
+    )
+    engine!!.start()
+  }
+
+  /** Build an AudioRecord for the mic, falling back to mono if stereo isn't supported. */
+  private fun buildMicRecord(sampleRate: Int, channels: Int): AudioRecord {
+    fun make(ch: Int): AudioRecord {
+      val mask = if (ch == 1) AudioFormat.CHANNEL_IN_MONO else AudioFormat.CHANNEL_IN_STEREO
+      val minBuf = AudioRecord.getMinBufferSize(sampleRate, mask, AudioFormat.ENCODING_PCM_16BIT)
+      val bufSize = if (minBuf > 0) minBuf * 2 else sampleRate * ch
+      return AudioRecord(
+        MediaRecorder.AudioSource.MIC, sampleRate, mask, AudioFormat.ENCODING_PCM_16BIT, bufSize
+      )
+    }
+    var record = make(channels)
+    if (record.state != AudioRecord.STATE_INITIALIZED && channels != 1) {
+      try { record.release() } catch (_: Exception) {}
+      record = make(1)
+    }
+    if (record.state != AudioRecord.STATE_INITIALIZED) {
+      try { record.release() } catch (_: Exception) {}
+      throw IllegalStateException("Could not initialize microphone capture")
+    }
+    return record
+  }
+}

package/expo-module.config.json

@@ -0,0 +1,10 @@
+{
+  "platforms": ["android"],
+  "android": {
+    "modules": [
+      "expo.modules.systemaudiocapture.SystemAudioCaptureModule",
+      "expo.modules.systemaudiocapture.VbanReceiverModule",
+      "expo.modules.systemaudiocapture.VbanSenderModule"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@parastud/react-native-vban",
+  "version": "0.1.0",
+  "description": "VBAN (VB-Audio Network) audio-over-IP for React Native / Expo — native UDP send & receive, Android system-audio capture via MediaProjection, and a pure-TypeScript VBAN codec. Interoperates with Voicemeeter and other VBAN endpoints.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "author": "Parastud <tech@rastaa.ai>",
+  "license": "MIT",
+  "keywords": [
+    "vban",
+    "voicemeeter",
+    "audio-over-ip",
+    "udp",
+    "react-native",
+    "expo",
+    "android",
+    "audio",
+    "streaming",
+    "mediaprojection"
+  ],
+  "files": [
+    "src",
+    "android",
+    "expo-module.config.json",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "expo": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "expo": {
+    "platforms": ["android"]
+  }
+}

package/src/NativeVbanReceiver.ts

@@ -0,0 +1,71 @@
+/**
+ * JS wrapper over the native `VbanNativeReceiver` module. The native side owns
+ * the UDP socket + AudioTrack playback; here we just start/stop it and relay the
+ * throttled stats events used to drive the meters and stream list.
+ */
+
+import { requireOptionalNativeModule } from 'expo-modules-core';
+
+export interface VbanStatsEvent {
+  streamName: string;
+  address: string;
+  sampleRate: number;
+  channels: number;
+  level: number;
+  dropped: number;
+  packets: number;
+}
+
+interface NativeReceiver {
+  start(port: number, filter: string | null): Promise<void>;
+  stop(): Promise<void>;
+  addListener(event: 'onStats', cb: (e: VbanStatsEvent) => void): { remove(): void };
+  addListener(event: 'onError', cb: (e: { message: string }) => void): { remove(): void };
+}
+
+const Native = requireOptionalNativeModule<NativeReceiver>('VbanNativeReceiver');
+
+/** True when the native receive+play path is available in this build. */
+export function isNativeReceiverAvailable(): boolean {
+  return Native != null;
+}
+
+export class NativeVbanReceiver {
+  private statsSub: { remove(): void } | null = null;
+  private errSub: { remove(): void } | null = null;
+  private running = false;
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  async start(
+    opts: { port: number; streamNameFilter?: string },
+    onStats: (e: VbanStatsEvent) => void,
+    onError?: (message: string) => void,
+  ): Promise<void> {
+    if (!Native) throw new Error('Native receiver not available in this build');
+    if (this.running) return;
+
+    this.statsSub = Native.addListener('onStats', onStats);
+    this.errSub = Native.addListener('onError', (e) => onError?.(e.message));
+
+    await Native.start(opts.port, opts.streamNameFilter ?? null);
+    this.running = true;
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    this.statsSub?.remove();
+    this.statsSub = null;
+    this.errSub?.remove();
+    this.errSub = null;
+    if (Native) {
+      try {
+        await Native.stop();
+      } catch {
+        // ignore
+      }
+    }
+  }
+}

package/src/NativeVbanSender.ts

@@ -0,0 +1,131 @@
+/**
+ * JS wrapper over the native `VbanNativeSender` module. Native code owns the
+ * capture + VBAN packetization + UDP send, so the JS bridge is never in the hot
+ * path (evenly paced packets, no receiver-side jitter). We only start/stop it
+ * and relay the throttled level stats.
+ */
+
+import { requireOptionalNativeModule } from 'expo-modules-core';
+import { PermissionsAndroid, Platform } from 'react-native';
+
+import type { SendSource } from './types';
+
+interface NativeSender {
+  startMic(
+    host: string,
+    port: number,
+    streamName: string,
+    sampleRate: number,
+    channels: number,
+  ): Promise<void>;
+  startDevice(
+    host: string,
+    port: number,
+    streamName: string,
+    sampleRate: number,
+    channels: number,
+  ): Promise<void>;
+  stop(): Promise<void>;
+  addListener(event: 'onStats', cb: (e: { level: number; packets: number }) => void): { remove(): void };
+  addListener(event: 'onError', cb: (e: { message: string }) => void): { remove(): void };
+}
+
+interface NativeCapture {
+  isSupported(): boolean;
+  requestPermission(): Promise<boolean>;
+}
+
+const Native = requireOptionalNativeModule<NativeSender>('VbanNativeSender');
+const Capture = requireOptionalNativeModule<NativeCapture>('SystemAudioCapture');
+
+export function isNativeSenderAvailable(): boolean {
+  return Native != null;
+}
+
+/** True when device (system) audio capture is supported on this OS/build. */
+export function isDeviceCaptureSupported(): boolean {
+  try {
+    return Capture != null && Capture.isSupported();
+  } catch {
+    return false;
+  }
+}
+
+async function ensureMicPermission(): Promise<void> {
+  if (Platform.OS !== 'android') return;
+  const result = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.RECORD_AUDIO);
+  if (result !== PermissionsAndroid.RESULTS.GRANTED) {
+    throw new Error('Microphone permission denied');
+  }
+}
+
+export interface NativeSendConfig {
+  host: string;
+  port: number;
+  streamName: string;
+  sampleRate: number;
+  channels: number;
+  source: SendSource;
+}
+
+export class NativeVbanSender {
+  private statsSub: { remove(): void } | null = null;
+  private errSub: { remove(): void } | null = null;
+  private running = false;
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  async start(
+    config: NativeSendConfig,
+    onStats: (level: number) => void,
+    onError?: (message: string) => void,
+  ): Promise<void> {
+    if (!Native) throw new Error('Native sender not available in this build');
+    if (this.running) return;
+
+    // Both mic and device capture use AudioRecord, which needs the mic permission.
+    await ensureMicPermission();
+
+    this.statsSub = Native.addListener('onStats', (e) => onStats(e.level));
+    this.errSub = Native.addListener('onError', (e) => onError?.(e.message));
+
+    if (config.source === 'device') {
+      if (!Capture) throw new Error('Device audio capture not available');
+      const granted = await Capture.requestPermission();
+      if (!granted) throw new Error('Screen/audio capture was not allowed');
+      await Native.startDevice(
+        config.host,
+        config.port,
+        config.streamName,
+        config.sampleRate,
+        config.channels,
+      );
+    } else {
+      await Native.startMic(
+        config.host,
+        config.port,
+        config.streamName,
+        config.sampleRate,
+        config.channels,
+      );
+    }
+    this.running = true;
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    this.statsSub?.remove();
+    this.statsSub = null;
+    this.errSub?.remove();
+    this.errSub = null;
+    if (Native) {
+      try {
+        await Native.stop();
+      } catch {
+        // ignore
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @parastud/react-native-vban
+ *
+ * VBAN (VB-Audio Network) audio-over-IP for React Native / Expo.
+ *
+ *  - Native UDP receive + AudioTrack playback  (VbanNativeReceiver)
+ *  - Native capture + VBAN + UDP send          (VbanNativeSender)
+ *  - Android system/playback audio capture via MediaProjection
+ *  - A pure-TypeScript VBAN codec (packet encode/decode + PCM conversion)
+ *
+ * Android-only for now. Interoperates with Voicemeeter and other VBAN endpoints.
+ */
+
+// Pure-TS VBAN codec (framework-agnostic).
+export * from './vban';
+
+// Shared types.
+export * from './types';
+
+// Native receive + send.
+export {
+  NativeVbanReceiver,
+  isNativeReceiverAvailable,
+  type VbanStatsEvent,
+} from './NativeVbanReceiver';
+export {
+  NativeVbanSender,
+  isNativeSenderAvailable,
+  isDeviceCaptureSupported,
+  type NativeSendConfig,
+} from './NativeVbanSender';

package/src/types.ts

@@ -0,0 +1,17 @@
+/** Where outbound audio is captured from. */
+export type SendSource = 'mic' | 'device';
+
+/** A VBAN audio stream the receiver has seen, for showing a picker/list in UI. */
+export interface DiscoveredStream {
+  key: string;
+  streamName: string;
+  address: string;
+  port: number;
+  sampleRate: number;
+  channels: number;
+  dataType: number;
+  /** Most recent peak level [0, 1]. */
+  level: number;
+  packets: number;
+  dropped: number;
+}

package/src/vban/constants.ts

@@ -0,0 +1,93 @@
+/**
+ * VBAN (VB-Audio Network) protocol constants.
+ *
+ * Reference: VBAN packet specification by VB-Audio.
+ * A VBAN packet = 28-byte header + payload. All multi-byte fields are
+ * little-endian. The header layout is:
+ *
+ *   offset  size  field
+ *   0       4     magic 'VBAN'
+ *   4       1     formatSR   : bits 0-4 sample-rate index, bits 5-7 sub-protocol
+ *   5       1     formatNBS  : samples-per-frame minus 1   (1..256)
+ *   6       1     formatNBC  : channels minus 1            (1..256)
+ *   7       1     formatBIT  : bits 0-2 data type, bit 3 reserved, bits 4-7 codec
+ *   8       16    streamName : ASCII, NUL-padded
+ *   24      4     frameCount : uint32 little-endian
+ *   28      ..    payload
+ */
+
+export const VBAN_MAGIC = 0x4e414256; // 'VBAN' read as little-endian uint32 ('V'=0x56 first byte)
+export const VBAN_HEADER_SIZE = 28;
+export const VBAN_STREAMNAME_SIZE = 16;
+
+/** Default UDP port used by VBAN. */
+export const VBAN_DEFAULT_PORT = 6980;
+
+/**
+ * Max audio payload bytes per packet (keeps the whole datagram under a typical
+ * MTU). Constraint from the spec: nbc * nbs * sampleSize <= this value.
+ */
+export const VBAN_MAX_PAYLOAD = 1436;
+
+/** Sample-rate table, indexed by the 5-bit sample-rate field. */
+export const VBAN_SAMPLE_RATES = [
+  6000, 12000, 24000, 48000, 96000, 192000, 384000,
+  8000, 16000, 32000, 64000, 128000, 256000, 512000,
+  11025, 22050, 44100, 88200, 176400, 352800, 705600,
+] as const;
+
+/** Sub-protocol, stored in bits 5-7 of formatSR. */
+export enum VbanProtocol {
+  Audio = 0x00,
+  Serial = 0x20,
+  Text = 0x40,
+  Service = 0x60,
+}
+
+/** Data type of a single sample, stored in bits 0-2 of formatBIT. */
+export enum VbanDataType {
+  Byte8 = 0x00, // signed 8-bit
+  Int16 = 0x01,
+  Int24 = 0x02,
+  Int32 = 0x03,
+  Float32 = 0x04,
+  Float64 = 0x05,
+  Bits12 = 0x06,
+  Bits10 = 0x07,
+}
+
+/** Codec, stored in bits 4-7 of formatBIT. Only PCM is uncompressed. */
+export enum VbanCodec {
+  PCM = 0x00,
+  VBCA = 0x10, // VB-Audio AOIP codec (compressed)
+  VBCV = 0x20, // VB-Audio VOIP codec (compressed)
+  User = 0xf0,
+}
+
+/** Size in bytes of one sample for a given data type (PCM only). */
+export const DATA_TYPE_SIZE: Record<VbanDataType, number> = {
+  [VbanDataType.Byte8]: 1,
+  [VbanDataType.Int16]: 2,
+  [VbanDataType.Int24]: 3,
+  [VbanDataType.Int32]: 4,
+  [VbanDataType.Float32]: 4,
+  [VbanDataType.Float64]: 8,
+  [VbanDataType.Bits12]: 2, // packed oddly; not supported for encode/decode yet
+  [VbanDataType.Bits10]: 2,
+};
+
+/** Bit masks for the packed header fields. */
+export const MASK_SR_INDEX = 0x1f;
+export const MASK_PROTOCOL = 0xe0;
+export const MASK_DATA_TYPE = 0x07;
+export const MASK_CODEC = 0xf0;
+
+/** Look up the Hz value for a sample-rate index, or undefined if out of range. */
+export function sampleRateFromIndex(index: number): number | undefined {
+  return VBAN_SAMPLE_RATES[index];
+}
+
+/** Find the sample-rate index for a Hz value, or -1 if it is not a VBAN rate. */
+export function indexFromSampleRate(hz: number): number {
+  return VBAN_SAMPLE_RATES.indexOf(hz as (typeof VBAN_SAMPLE_RATES)[number]);
+}

package/src/vban/index.ts

@@ -0,0 +1,3 @@
+export * from './constants';
+export * from './packet';
+export * from './pcm';

package/src/vban/packet.ts

@@ -0,0 +1,159 @@
+/**
+ * VBAN packet header encode/decode. Pure, dependency-free, and RN/Hermes-safe
+ * (uses only Uint8Array + DataView, no Node Buffer).
+ */
+
+import {
+  DATA_TYPE_SIZE,
+  MASK_CODEC,
+  MASK_DATA_TYPE,
+  MASK_PROTOCOL,
+  MASK_SR_INDEX,
+  VBAN_HEADER_SIZE,
+  VBAN_STREAMNAME_SIZE,
+  VbanCodec,
+  VbanDataType,
+  VbanProtocol,
+  indexFromSampleRate,
+  sampleRateFromIndex,
+} from './constants';
+
+export interface VbanHeader {
+  /** Sub-protocol (audio, serial, text, service). */
+  protocol: VbanProtocol;
+  /** Sample rate in Hz. Must be one of the VBAN rates. */
+  sampleRate: number;
+  /** Samples per channel in this packet (1..256). */
+  samplesPerFrame: number;
+  /** Number of channels (1..256). */
+  channels: number;
+  /** Sample data type. */
+  dataType: VbanDataType;
+  /** Codec (only PCM is uncompressed and supported here). */
+  codec: VbanCodec;
+  /** Stream name, up to 16 ASCII chars. */
+  streamName: string;
+  /** Frame counter, uint32. Increments per packet sent on a stream. */
+  frameCount: number;
+}
+
+export interface VbanPacket {
+  header: VbanHeader;
+  /** Raw payload bytes (the audio samples, still in their wire data type). */
+  payload: Uint8Array;
+}
+
+const MAGIC = [0x56, 0x42, 0x41, 0x4e]; // 'V','B','A','N'
+
+/** Write up to 16 ASCII bytes of `name` into `dst` at `offset`, NUL-padded. */
+function writeStreamName(dst: Uint8Array, offset: number, name: string): void {
+  for (let i = 0; i < VBAN_STREAMNAME_SIZE; i++) {
+    const code = i < name.length ? name.charCodeAt(i) & 0x7f : 0;
+    dst[offset + i] = code;
+  }
+}
+
+/** Read a NUL-terminated ASCII stream name of at most 16 bytes. */
+function readStreamName(src: Uint8Array, offset: number): string {
+  let out = '';
+  for (let i = 0; i < VBAN_STREAMNAME_SIZE; i++) {
+    const code = src[offset + i];
+    if (code === 0) break;
+    out += String.fromCharCode(code);
+  }
+  return out;
+}
+
+/** Encode a 28-byte VBAN header into `out` at `offset` (defaults to a new array). */
+export function encodeHeader(
+  header: VbanHeader,
+  out: Uint8Array = new Uint8Array(VBAN_HEADER_SIZE),
+  offset = 0,
+): Uint8Array {
+  const srIndex = indexFromSampleRate(header.sampleRate);
+  if (srIndex < 0) {
+    throw new Error(`Unsupported VBAN sample rate: ${header.sampleRate}`);
+  }
+  if (header.samplesPerFrame < 1 || header.samplesPerFrame > 256) {
+    throw new Error(`samplesPerFrame out of range (1..256): ${header.samplesPerFrame}`);
+  }
+  if (header.channels < 1 || header.channels > 256) {
+    throw new Error(`channels out of range (1..256): ${header.channels}`);
+  }
+
+  const view = new DataView(out.buffer, out.byteOffset + offset, VBAN_HEADER_SIZE);
+  out[offset + 0] = MAGIC[0];
+  out[offset + 1] = MAGIC[1];
+  out[offset + 2] = MAGIC[2];
+  out[offset + 3] = MAGIC[3];
+  out[offset + 4] = (srIndex & MASK_SR_INDEX) | (header.protocol & MASK_PROTOCOL);
+  out[offset + 5] = header.samplesPerFrame - 1;
+  out[offset + 6] = header.channels - 1;
+  out[offset + 7] = (header.dataType & MASK_DATA_TYPE) | (header.codec & MASK_CODEC);
+  writeStreamName(out, offset + 8, header.streamName);
+  view.setUint32(24, header.frameCount >>> 0, true);
+  return out;
+}
+
+/** Decode a 28-byte VBAN header from `src` at `offset`. Throws on bad magic. */
+export function decodeHeader(src: Uint8Array, offset = 0): VbanHeader {
+  if (src.length - offset < VBAN_HEADER_SIZE) {
+    throw new Error('Buffer too small for a VBAN header');
+  }
+  if (
+    src[offset + 0] !== MAGIC[0] ||
+    src[offset + 1] !== MAGIC[1] ||
+    src[offset + 2] !== MAGIC[2] ||
+    src[offset + 3] !== MAGIC[3]
+  ) {
+    throw new Error('Not a VBAN packet (bad magic)');
+  }
+
+  const view = new DataView(src.buffer, src.byteOffset + offset, VBAN_HEADER_SIZE);
+  const formatSR = src[offset + 4];
+  const formatBIT = src[offset + 7];
+
+  const srIndex = formatSR & MASK_SR_INDEX;
+  const sampleRate = sampleRateFromIndex(srIndex);
+  if (sampleRate === undefined) {
+    throw new Error(`Reserved VBAN sample-rate index: ${srIndex}`);
+  }
+
+  return {
+    protocol: (formatSR & MASK_PROTOCOL) as VbanProtocol,
+    sampleRate,
+    samplesPerFrame: src[offset + 5] + 1,
+    channels: src[offset + 6] + 1,
+    dataType: (formatBIT & MASK_DATA_TYPE) as VbanDataType,
+    codec: (formatBIT & MASK_CODEC) as VbanCodec,
+    streamName: readStreamName(src, offset + 8),
+    frameCount: view.getUint32(24, true),
+  };
+}
+
+/**
+ * Build a complete VBAN datagram from a header and already-encoded payload
+ * bytes. `header.samplesPerFrame`/`channels`/`dataType` should match the
+ * payload length; a mismatch throws to catch bugs early.
+ */
+export function encodePacket(header: VbanHeader, payload: Uint8Array): Uint8Array {
+  const sampleSize = DATA_TYPE_SIZE[header.dataType];
+  const expected = header.samplesPerFrame * header.channels * sampleSize;
+  if (payload.length !== expected) {
+    throw new Error(
+      `Payload length ${payload.length} != expected ${expected} ` +
+        `(${header.samplesPerFrame} samples x ${header.channels} ch x ${sampleSize} bytes)`,
+    );
+  }
+  const packet = new Uint8Array(VBAN_HEADER_SIZE + payload.length);
+  encodeHeader(header, packet, 0);
+  packet.set(payload, VBAN_HEADER_SIZE);
+  return packet;
+}
+
+/** Parse a received datagram into its header and payload view. */
+export function decodePacket(datagram: Uint8Array): VbanPacket {
+  const header = decodeHeader(datagram, 0);
+  const payload = datagram.subarray(VBAN_HEADER_SIZE);
+  return { header, payload };
+}