@agentdance/node-webrtc-rtp 1.0.0

package/src/rtp.ts

@@ -0,0 +1,176 @@
+/**
+ * RTP packet encode/decode — RFC 3550 Section 5.1
+ */
+
+import type { RtpPacket } from './types.js';
+import {
+  parseExtensionValues,
+  serializeExtension,
+  ONE_BYTE_PROFILE,
+  TWO_BYTE_PROFILE,
+} from './extension.js';
+
+/** Minimum RTP header size (no CSRC, no extension) */
+const RTP_MIN_HEADER = 12;
+
+/**
+ * Returns true if the buffer looks like an RTP packet:
+ *   - version == 2
+ *   - payload type NOT in the RTCP range 200–204
+ *   - at least 12 bytes
+ */
+export function isRtpPacket(buf: Buffer): boolean {
+  if (buf.length < RTP_MIN_HEADER) return false;
+  const firstByte = buf[0];
+  if (firstByte === undefined) return false;
+  const version = (firstByte >> 6) & 0x03;
+  if (version !== 2) return false;
+  const secondByte = buf[1];
+  if (secondByte === undefined) return false;
+  // RTCP PT occupies the full second byte (200–207); check raw value, not masked
+  if (secondByte >= 200 && secondByte <= 207) return false;
+  return true;
+}
+
+/**
+ * Decode an RTP packet from a Buffer.
+ * Throws if the buffer is malformed or too short.
+ */
+export function decodeRtp(buf: Buffer): RtpPacket {
+  if (buf.length < RTP_MIN_HEADER) {
+    throw new RangeError(`RTP buffer too short: ${buf.length}`);
+  }
+
+  const byte0 = buf[0]!;
+  const byte1 = buf[1]!;
+
+  const version = (byte0 >> 6) & 0x03;
+  if (version !== 2) {
+    throw new Error(`Invalid RTP version: ${version}`);
+  }
+
+  const padding = Boolean(byte0 & 0x20);
+  const hasExtension = Boolean(byte0 & 0x10);
+  const csrcCount = byte0 & 0x0f;
+
+  const marker = Boolean(byte1 & 0x80);
+  const payloadType = byte1 & 0x7f;
+
+  const sequenceNumber = buf.readUInt16BE(2);
+  const timestamp = buf.readUInt32BE(4);
+  const ssrc = buf.readUInt32BE(8);
+
+  let offset = RTP_MIN_HEADER;
+
+  // CSRC list
+  if (buf.length < offset + csrcCount * 4) {
+    throw new RangeError('RTP buffer too short for CSRC list');
+  }
+  const csrcs: number[] = [];
+  for (let i = 0; i < csrcCount; i++) {
+    csrcs.push(buf.readUInt32BE(offset));
+    offset += 4;
+  }
+
+  // Header extension
+  let headerExtension: RtpPacket['headerExtension'];
+  if (hasExtension) {
+    if (buf.length < offset + 4) {
+      throw new RangeError('RTP buffer too short for extension header');
+    }
+    const extProfile = buf.readUInt16BE(offset);
+    const extLengthWords = buf.readUInt16BE(offset + 2);
+    offset += 4;
+    const extBodyLen = extLengthWords * 4;
+    if (buf.length < offset + extBodyLen) {
+      throw new RangeError('RTP buffer too short for extension body');
+    }
+    const extBody = buf.subarray(offset, offset + extBodyLen) as Buffer;
+    offset += extBodyLen;
+
+    const values = parseExtensionValues(extProfile, extBody);
+    headerExtension = { id: extProfile, values };
+  }
+
+  // Payload
+  let payloadEnd = buf.length;
+  if (padding) {
+    const padLen = buf[buf.length - 1]!;
+    payloadEnd = buf.length - padLen;
+  }
+  const payload = Buffer.from(buf.subarray(offset, payloadEnd));
+
+  const result: RtpPacket = {
+    version: 2,
+    padding,
+    extension: hasExtension,
+    csrcCount,
+    marker,
+    payloadType,
+    sequenceNumber,
+    timestamp,
+    ssrc,
+    csrcs,
+    payload,
+  };
+  if (headerExtension !== undefined) {
+    result.headerExtension = headerExtension;
+  }
+  return result;
+}
+
+/**
+ * Encode an RTP packet into a Buffer.
+ */
+export function encodeRtp(packet: RtpPacket): Buffer {
+  const csrcCount = packet.csrcs.length;
+
+  // Build extension bytes if present
+  let extBuf: Buffer = Buffer.alloc(0);
+  if (packet.headerExtension) {
+    extBuf = serializeExtension(packet.headerExtension);
+  }
+
+  // Build padding
+  let padBuf: Buffer = Buffer.alloc(0);
+  if (packet.padding) {
+    // Add minimal 1-byte padding (caller controls actual padding amount via payload)
+    // The last byte of padding holds the count.
+    // We always emit padding as part of the payload in this implementation.
+    // If the caller set padding=true the payload should already include it.
+  }
+
+  const headerLen = RTP_MIN_HEADER + csrcCount * 4;
+  const totalLen = headerLen + extBuf.length + packet.payload.length + padBuf.length;
+  const buf = Buffer.allocUnsafe(totalLen);
+
+  const hasExt = packet.headerExtension !== undefined || packet.extension;
+
+  const byte0 =
+    (2 << 6) |
+    (packet.padding ? 0x20 : 0) |
+    (hasExt ? 0x10 : 0) |
+    (csrcCount & 0x0f);
+  const byte1 = ((packet.marker ? 1 : 0) << 7) | (packet.payloadType & 0x7f);
+
+  buf[0] = byte0;
+  buf[1] = byte1;
+  buf.writeUInt16BE(packet.sequenceNumber, 2);
+  buf.writeUInt32BE(packet.timestamp >>> 0, 4);
+  buf.writeUInt32BE(packet.ssrc >>> 0, 8);
+
+  let offset = RTP_MIN_HEADER;
+  for (const csrc of packet.csrcs) {
+    buf.writeUInt32BE(csrc >>> 0, offset);
+    offset += 4;
+  }
+
+  if (extBuf.length > 0) {
+    extBuf.copy(buf, offset);
+    offset += extBuf.length;
+  }
+
+  packet.payload.copy(buf, offset);
+
+  return buf;
+}

package/src/sequence.ts

@@ -0,0 +1,59 @@
+/**
+ * Wrap-around aware sequence number utilities for RTP (RFC 3550 Section A.1).
+ * Sequence numbers are 16-bit unsigned (0–65535).
+ */
+
+const MAX_SEQ = 0x10000; // 65536
+const HALF_MAX_SEQ = 0x8000; // 32768
+
+/**
+ * Returns a - b, wrap-around aware.
+ * Result is in range (-32768, 32768].
+ */
+export function seqDiff(a: number, b: number): number {
+  const diff = ((a - b) & 0xffff) >>> 0;
+  if (diff === 0) return 0;
+  // If diff >= half the range, it wrapped around in the negative direction
+  return diff < HALF_MAX_SEQ ? diff : diff - MAX_SEQ;
+}
+
+/** Returns true if a < b (wrap-around aware) */
+export function seqLt(a: number, b: number): boolean {
+  return seqDiff(a, b) < 0;
+}
+
+/** Returns true if a <= b (wrap-around aware) */
+export function seqLte(a: number, b: number): boolean {
+  return seqDiff(a, b) <= 0;
+}
+
+/** Returns true if a > b (wrap-around aware) */
+export function seqGt(a: number, b: number): boolean {
+  return seqDiff(a, b) > 0;
+}
+
+// NTP epoch is Jan 1, 1900; Unix epoch is Jan 1, 1970 — difference in seconds
+const NTP_UNIX_OFFSET_S = BigInt(70 * 365 * 24 * 3600 + 17 * 24 * 3600); // 70 years + 17 leap days
+
+/**
+ * Convert a 64-bit NTP timestamp to Unix milliseconds.
+ * NTP format: upper 32 bits = seconds since 1900-01-01,
+ *             lower 32 bits = fractional seconds.
+ */
+export function ntpToUnix(ntp: bigint): number {
+  const seconds = (ntp >> 32n) - NTP_UNIX_OFFSET_S;
+  const fraction = ntp & 0xffffffffn;
+  const ms = (fraction * 1000n) >> 32n;
+  return Number(seconds) * 1000 + Number(ms);
+}
+
+/**
+ * Convert Unix milliseconds to a 64-bit NTP timestamp.
+ */
+export function unixToNtp(ms: number): bigint {
+  const totalMs = BigInt(ms);
+  const seconds = totalMs / 1000n + NTP_UNIX_OFFSET_S;
+  const remainder = totalMs % 1000n;
+  const fraction = (remainder * (1n << 32n)) / 1000n;
+  return (seconds << 32n) | fraction;
+}

package/src/types.ts

@@ -0,0 +1,129 @@
+// RFC 3550 RTP/RTCP types
+
+export interface RtpPacket {
+  version: 2;
+  padding: boolean;
+  extension: boolean;
+  csrcCount: number;
+  marker: boolean;
+  payloadType: number;
+  sequenceNumber: number;
+  timestamp: number;
+  ssrc: number;
+  csrcs: number[];
+  headerExtension?: RtpHeaderExtension;
+  payload: Buffer;
+}
+
+export interface RtpHeaderExtension {
+  id: number; // profile: 0xBEDE = one-byte, 0x1000 = two-byte
+  values: RtpExtensionValue[];
+}
+
+export interface RtpExtensionValue {
+  id: number;
+  data: Buffer;
+}
+
+export enum RtcpPacketType {
+  SR = 200,
+  RR = 201,
+  SDES = 202,
+  BYE = 203,
+  APP = 204,
+  TransportFeedback = 205,
+  PayloadFeedback = 206,
+}
+
+export interface RtcpHeader {
+  version: 2;
+  padding: boolean;
+  count: number; // also FMT for feedback packets
+  packetType: RtcpPacketType;
+  length: number; // in 32-bit words minus 1
+}
+
+export interface RtcpSenderReport {
+  ssrc: number;
+  ntpTimestamp: bigint; // 64-bit NTP timestamp
+  rtpTimestamp: number;
+  packetCount: number;
+  octetCount: number;
+  reportBlocks: ReportBlock[];
+}
+
+export interface RtcpReceiverReport {
+  ssrc: number;
+  reportBlocks: ReportBlock[];
+}
+
+export interface ReportBlock {
+  ssrc: number;
+  fractionLost: number; // 8-bit fraction
+  cumulativeLost: number; // 24-bit signed
+  extendedHighestSeq: number;
+  jitter: number;
+  lastSR: number;
+  delaySinceLastSR: number;
+}
+
+export interface RtcpSdes {
+  chunks: SdesChunk[];
+}
+
+export interface SdesChunk {
+  ssrc: number;
+  items: SdesItem[];
+}
+
+export interface SdesItem {
+  type: number; // 1=CNAME, 2=NAME, 3=EMAIL, 4=PHONE, 5=LOC, 6=TOOL, 7=NOTE, 8=PRIV
+  text: string;
+}
+
+export interface RtcpBye {
+  ssrcs: number[];
+  reason?: string;
+}
+
+// Feedback messages (RFC 4585)
+export interface RtcpNack {
+  senderSsrc: number;
+  mediaSsrc: number;
+  pid: number;
+  blp: number; // bitmask of following lost packets
+}
+
+export interface RtcpPli {
+  senderSsrc: number;
+  mediaSsrc: number;
+}
+
+export interface RtcpFir {
+  senderSsrc: number;
+  entries: FirEntry[];
+}
+
+export interface FirEntry {
+  ssrc: number;
+  seqNumber: number;
+}
+
+// REMB (draft-alvestrand-rmcat-remb)
+export interface RtcpRemb {
+  senderSsrc: number;
+  mediaSsrc: number;
+  bitrate: number; // bits per second
+  ssrcs: number[];
+}
+
+export type RtcpPacket =
+  | { type: 'sr'; packet: RtcpSenderReport }
+  | { type: 'rr'; packet: RtcpReceiverReport }
+  | { type: 'sdes'; packet: RtcpSdes }
+  | { type: 'bye'; packet: RtcpBye }
+  | { type: 'nack'; packet: RtcpNack }
+  | { type: 'pli'; packet: RtcpPli }
+  | { type: 'fir'; packet: RtcpFir }
+  | { type: 'remb'; packet: RtcpRemb }
+  | { type: 'unknown'; raw: Buffer };