GStreamer Kit

A modern Node.js binding for GStreamer, providing high-level APIs for multimedia streaming and processing. This project modernizes the legacy node-gstreamer-superficial library with contemporary technologies and improved runtime support.

Project Goals & Modernization

This project represents a complete modernization of the old node-gstreamer-superficial library, featuring:

Modern Runtime Support

N-API instead of NAN: Uses Node-API (N-API) for better runtime stability and version independence
Multi-runtime compatibility: Supports Node.js 16+, Bun 1.0+, and other V8-based runtimes
Version independence: Not bound to specific V8 versions, ensuring longevity

Modern Build System

Rollup bundling: Generates both CommonJS and ESM modules for maximum compatibility
TypeScript-first: Complete TypeScript support with full type definitions
GYP build system: Robust C++ compilation with proper dependency management
Modern testing: Uses Vitest for fast, concurrent testing instead of legacy test frameworks

Enhanced Developer Experience

Full TypeScript support: Complete type definitions for all APIs
ESM/CJS dual packaging: Works with both import and require statements
Comprehensive testing: Extensive test coverage with modern test runner
Better documentation: Clear examples and API documentation

Complete Feature Set

Core Pipeline Features

Pipeline Management: Create, play, pause, stop GStreamer pipelines
State Management: Comprehensive state change handling with detailed results
Element Access: Get elements by name with proper typing
Property System: Get/set element properties with type safety

Advanced Data Access

App Sources & Sinks: Two approaches for data access:
- Pull-based: Explicitly request samples with getSample() (async, controlled timing)
- Push-based: Reactive callbacks with onSample() (automatic, real-time)
Pad Probes: Add/remove event-driven callbacks to intercept comprehensive buffer data
Buffer Analysis: Extract raw data, timing information, flags, caps, and metadata

Media Processing

RTP Support: Extract RTP metadata including timestamps, sequence numbers, SSRC, payload type
Seeking: Frame-accurate seeking with success feedback
Query System: Position and duration queries in seconds
Message Bus: Handle GStreamer messages (EOS, errors, warnings, state changes)

Runtime Features

Multi-format Support: Video, audio, containers, streaming protocols
Codec Support: H.264, H.265, VP8, VP9, AV1, and more through GStreamer plugins
Network Streaming: RTP, RTSP, HLS, DASH, WebRTC protocols
Hardware Acceleration: GPU-accelerated encoding/decoding where available

Installation

npm install gst-kit

System Requirements

Runtime: Node.js 16+ or Bun 1.0+ (Deno is not supported)
System: GStreamer 1.14 or higher (1.26+ recommended)
Build Tools: Python 2.7 or 3.x (for node-gyp), pkg-config
Dependencies: GStreamer development packages and plugins

Platform-Specific Installation Guide

Cross-Platform Alternative: For any operating system, you can use the setup-cpp tool to automatically install compilers, build tools, and package managers:

# Install development tools across platforms (Windows, macOS, Linux)
npx setup-cpp --compiler auto --pkg-config true

# On Windows, this can also install Chocolatey:
npx setup-cpp --compiler msvc --pkg-config true --choco true

Ubuntu/Debian (Recommended for Production)

Option A: Package Manager (Traditional)

# Update package list
sudo apt-get update

# Install GStreamer core development packages
sudo apt-get install -y \
  libgstreamer1.0-dev \
  libgstreamer-plugins-base1.0-dev \
  libgstreamer-plugins-bad1.0-dev \
  pkg-config

# Install GStreamer plugins (essential for most use cases)
sudo apt-get install -y \
  gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad \
  gstreamer1.0-plugins-ugly \
  gstreamer1.0-libav

# Install build tools
sudo apt-get install -y build-essential python3

Option B: Cross-Platform Setup with setup-cpp (Ubuntu)

# Install build tools automatically
npx setup-cpp --compiler auto --pkg-config true

# Then install GStreamer packages
sudo apt-get update
sudo apt-get install -y \
  libgstreamer1.0-dev \
  libgstreamer-plugins-base1.0-dev \
  libgstreamer-plugins-bad1.0-dev \
  gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad \
  gstreamer1.0-plugins-ugly \
  gstreamer1.0-libav

Verification:

pkg-config --cflags --libs gstreamer-1.0
gst-launch-1.0 --version

macOS (Homebrew)

Option A: Homebrew (Traditional)

# Install GStreamer and plugins
brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly pkg-config

# Set environment variables (add to ~/.zshrc or ~/.bash_profile)
export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$PKG_CONFIG_PATH"
export LIBRARY_PATH="$(brew --prefix)/lib:$LIBRARY_PATH"
export LD_LIBRARY_PATH="$(brew --prefix)/lib:$LD_LIBRARY_PATH"

Option B: Cross-Platform Setup with setup-cpp (macOS)

# Install build tools automatically
npx setup-cpp --compiler auto --pkg-config true

# Then install GStreamer via Homebrew
brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly

# Set environment variables (add to ~/.zshrc or ~/.bash_profile)
export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$PKG_CONFIG_PATH"
export LIBRARY_PATH="$(brew --prefix)/lib:$LIBRARY_PATH"
export LD_LIBRARY_PATH="$(brew --prefix)/lib:$LD_LIBRARY_PATH"

Verification:

pkg-config --cflags --libs gstreamer-1.0
gst-launch-1.0 --version

Windows

Complete Installation:

Install Build Tools:

Option A: Manual Installation

# Install Visual Studio Build Tools 2019/2022 (Community edition is free)
# Download from: https://visualstudio.microsoft.com/downloads/

# Install pkg-config (REQUIRED for build to work)
choco install pkgconfiglite

Option B: Cross-Platform Setup with setup-cpp (Recommended)

# Use setup-cpp for automated toolchain installation (works on Windows, macOS, Linux)
# This tool can install compilers, package managers (including Chocolatey), and build systems
npx setup-cpp --compiler msvc --pkg-config true --choco true

Install GStreamer 1.26.2:

# Download both runtime and development MSI packages from:
# https://gstreamer.freedesktop.org/download/

# For 64-bit systems, download and install:
# - gstreamer-1.0-msvc-x86_64-1.26.2.msi (runtime)
# - gstreamer-1.0-devel-msvc-x86_64-1.26.2.msi (development)

# Install both MSI files by double-clicking or using:
# msiexec /i gstreamer-1.0-msvc-x86_64-1.26.2.msi /quiet
# msiexec /i gstreamer-1.0-devel-msvc-x86_64-1.26.2.msi /quiet

Set Environment Variables:

# Add to system PATH (via System Properties → Environment Variables):
C:\Program Files\gstreamer\1.0\msvc_x86_64\bin

# Add system environment variables:
GSTREAMER_1_0_ROOT_MSVC_X86_64=C:\Program Files\gstreamer\1.0\msvc_x86_64
PKG_CONFIG_PATH=C:\Program Files\gstreamer\1.0\msvc_x86_64\lib\pkgconfig

Verification:

# Verify pkg-config can find GStreamer (most important for building)
pkg-config --exists gstreamer-1.0; if ($LASTEXITCODE -eq 0) { Write-Host "GStreamer found" } else { Write-Host "GStreamer NOT found" }
pkg-config --cflags --libs gstreamer-1.0

Windows-Specific Troubleshooting:

If you encounter build errors after installation, try these common fixes:

PKG_CONFIG_PATH Issues:

# If GStreamer was installed to default location but pkg-config can't find it:
setx PKG_CONFIG_PATH "C:\Program Files\gstreamer\1.0\msvc_x86_64\lib\pkgconfig"

# Restart your terminal/command prompt after setting this variable
# Verify the fix:
pkg-config --exists gstreamer-1.0; if ($LASTEXITCODE -eq 0) { Write-Host "GStreamer found" } else { Write-Host "GStreamer NOT found" }

Missing pkg-config:

# pkg-config is absolutely required - install if missing:
choco install pkgconfiglite

# Or refresh your PATH if already installed:
refreshenv

GStreamer Location Mismatch:

# If GStreamer was installed to a different location, update PKG_CONFIG_PATH accordingly:
# For example, if installed to C:\gstreamer:
setx PKG_CONFIG_PATH "C:\gstreamer\1.0\msvc_x86_64\lib\pkgconfig"

Common Installation Issues

Problem: "Cannot find gstreamer-1.0"

Solution:

# Ubuntu/Debian
sudo apt-get install libgstreamer1.0-dev pkg-config

# macOS
brew install gstreamer pkg-config
export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$PKG_CONFIG_PATH"

# Windows (PowerShell)
# Ensure pkg-config is installed:
choco install pkgconfiglite

# Ensure environment variables are set correctly:
# GSTREAMER_1_0_ROOT_MSVC_X86_64=C:\Program Files\gstreamer\1.0\msvc_x86_64
# PKG_CONFIG_PATH=C:\Program Files\gstreamer\1.0\msvc_x86_64\lib\pkgconfig

# If GStreamer is installed but pkg-config can't find it, set PKG_CONFIG_PATH:
setx PKG_CONFIG_PATH "C:\Program Files\gstreamer\1.0\msvc_x86_64\lib\pkgconfig"

# Verify pkg-config can find GStreamer
pkg-config --exists gstreamer-1.0; if ($LASTEXITCODE -eq 0) { Write-Host "GStreamer found" } else { Write-Host "GStreamer NOT found" }

Problem: Missing plugins (playbin/decodebin errors)

Solution:

# Ubuntu/Debian - install plugin packages
sudo apt-get install gstreamer1.0-plugins-{base,good,bad,ugly} gstreamer1.0-libav

# macOS - install plugin packages
brew install gst-plugins-{base,good,bad,ugly}

# List available plugins
gst-inspect-1.0 | grep -i plugin

Problem: "Permission denied" on Linux

Solution:

# Add user to audio/video groups
sudo usermod -a -G audio,video $USER
# Logout and login again

# Or install PulseAudio for audio support
sudo apt-get install pulseaudio pulseaudio-utils

Docker Installation

For containerized applications:

# Ubuntu-based container
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    nodejs npm \
    libgstreamer1.0-dev \
    libgstreamer-plugins-base1.0-dev \
    libgstreamer-plugins-bad1.0-dev \
    gstreamer1.0-plugins-base \
    gstreamer1.0-plugins-good \
    gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-ugly \
    gstreamer1.0-libav \
    build-essential pkg-config python3 \
    && rm -rf /var/lib/apt/lists/*

# Install your application
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

Quick Start

Basic Pipeline

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("videotestsrc ! autovideosink");
await pipeline.play();

// Stop after 5 seconds
setTimeout(async () => {
  await pipeline.stop();
}, 5000);

Checking Element Availability

import { Pipeline } from "gst-kit";

// Check if specific GStreamer elements are available before using them
if (Pipeline.elementExists("x264enc")) {
  console.log("H.264 encoder is available");
  const pipeline = new Pipeline("videotestsrc ! x264enc ! mp4mux ! filesink location=output.mp4");
} else {
  console.log("x264enc not found, using alternative encoder");
  const pipeline = new Pipeline("videotestsrc ! vp8enc ! webmmux ! filesink location=output.webm");
}

// Check hardware acceleration support
const hasVaapi = Pipeline.elementExists("vaapih264enc");
const hasNvenc = Pipeline.elementExists("nvh264enc");
console.log(`VAAPI support: ${hasVaapi}, NVENC support: ${hasNvenc}`);

Working with AppSink (Pull-based Approach)

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("videotestsrc num-buffers=10 ! videoconvert ! appsink name=sink");
const sink = pipeline.getElementByName("sink");

if (sink?.type === "app-sink-element") {
  await pipeline.play();

  while (true) {
    const sample = await sink.getSample(); // Explicitly request samples
    if (!sample) break;

    console.log("Received frame:", sample.buffer?.length, "bytes");
  }

  await pipeline.stop();
}

Working with AppSink (Event-Driven/Push Approach)

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("videotestsrc num-buffers=10 ! videoconvert ! appsink name=sink");
const sink = pipeline.getElementByName("sink");

if (sink?.type === "app-sink-element") {
  let frameCount = 0;

  // Set up reactive callback - samples are pushed automatically
  const unsubscribe = sink.onSample(sample => {
    frameCount++;
    console.log(`Frame ${frameCount}:`, sample.buffer?.length, "bytes");

    if (frameCount === 10) {
      unsubscribe();
      pipeline.stop();
    }
  });

  await pipeline.play();
}

Working with AppSrc (Source Input)

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("appsrc name=source ! videoconvert ! autovideosink");
const source = pipeline.getElementByName("source");

if (source?.type === "app-src-element") {
  source.setElementProperty("caps", "video/x-raw,format=RGB,width=320,height=240");
  source.setElementProperty("is-live", true);

  await pipeline.play();

  // Push random RGB frames
  setInterval(() => {
    const buffer = Buffer.alloc(320 * 240 * 3);
    buffer.fill(Math.floor(Math.random() * 255));
    source.push(buffer);
  }, 33); // ~30 FPS
}

Working with AppSrc for Custom Data Sources (with EOS)

Use AppSrc with EOS when you need to process data that can't be handled by standard GStreamer elements like filesrc:

import { Pipeline } from "gst-kit";
import { createReadStream } from "fs";

// Real-world scenarios where AppSrc + EOS is needed:
// 1. Custom encrypted file formats
// 2. Network streams with custom protocols
// 3. Database BLOBs containing media data
// 4. Programmatically generated content with known duration
// 5. Multi-source aggregation

async function streamEncryptedVideoFile(encryptedFilePath) {
  const pipeline = new Pipeline("appsrc name=source ! h264parse ! avdec_h264 ! autovideosink");
  const source = pipeline.getElementByName("source");

  if (source?.type === "app-src-element") {
    source.setElementProperty("caps", "video/x-h264,stream-format=byte-stream");
    source.setElementProperty("is-live", false); // File-like behavior

    await pipeline.play();

    // Read and decrypt file chunks
    const encryptedStream = createReadStream(encryptedFilePath);

    for await (const encryptedChunk of encryptedStream) {
      // Decrypt the chunk (your custom decryption logic)
      const decryptedBuffer = await decryptChunk(encryptedChunk);
      source.push(decryptedBuffer);
    }

    // IMPORTANT: Signal end-of-stream when file is fully processed
    source.endOfStream();

    // Wait for natural completion
    while (true) {
      const message = await pipeline.busPop(1000);
      if (message?.type === "eos") {
        console.log("Encrypted file playback completed");
        break;
      }
    }

    await pipeline.stop();
  }
}

// Example: Stream from database BLOB
async function streamFromDatabase(mediaId) {
  const pipeline = new Pipeline("appsrc name=source ! decodebin ! autovideosink");
  const source = pipeline.getElementByName("source");

  if (source?.type === "app-src-element") {
    // Note: Let decodebin auto-detect format
    source.setElementProperty("is-live", false);

    await pipeline.play();

    // Stream media data from database in chunks
    const mediaChunks = await fetchMediaFromDatabase(mediaId);

    for (const chunk of mediaChunks) {
      source.push(chunk);
    }

    source.endOfStream(); // Signal completion

    // Handle completion
    while (true) {
      const message = await pipeline.busPop(1000);
      if (message?.type === "eos") break;
    }

    await pipeline.stop();
  }
}

// Placeholder functions - implement according to your needs
async function decryptChunk(encryptedData) {
  // Your decryption logic here
  return encryptedData; // Return decrypted buffer
}

async function fetchMediaFromDatabase(mediaId) {
  // Your database fetch logic here
  return []; // Return array of media chunks
}

Recording Programmatically Generated Streams to Files

For recording programmatically generated content (procedural video, custom visualizations, etc.) to video files:

import { Pipeline } from "gst-kit";
import path from "path";
import fs from "fs";

async function recordGeneratedVideoToFile() {
  const outputFile = path.join(process.cwd(), "recording.ogv");

  // Remove existing file if it exists
  if (fs.existsSync(outputFile)) {
    fs.unlinkSync(outputFile);
  }

  // Create recording pipeline (OGV/Theora is most reliable for programmatic content)
  const pipeline = new Pipeline(`
    appsrc name=mysource ! 
    videoconvert ! 
    theoraenc ! 
    oggmux ! 
    filesink location=${outputFile}
  `);

  const appsrc = pipeline.getElementByName("mysource");

  if (appsrc?.type === "app-src-element") {
    // Configure for file recording (not live streaming)
    appsrc.setElementProperty("caps", "video/x-raw,format=RGB,width=640,height=480,framerate=30/1");
    appsrc.setElementProperty("format", "time");
    appsrc.setElementProperty("is-live", false);
    appsrc.setElementProperty("do-timestamp", true);

    await pipeline.play();

    // Generate and push frames
    const frameCount = 300; // 10 seconds at 30fps
    const width = 640;
    const height = 480;
    const frameSize = width * height * 3; // RGB

    for (let i = 0; i < frameCount; i++) {
      // Generate frame data (replace with your content generation logic)
      const buffer = generateFrame(i, width, height);
      appsrc.push(buffer);

      if (i % 30 === 0) {
        console.log(`📹 Recorded ${i} frames (${i / 30} seconds)`);
      }
    }

    // CRITICAL: Signal end-of-stream when done generating content
    appsrc.endOfStream();

    // Wait for recording completion
    while (true) {
      const message = await pipeline.busPop(1000);
      if (!message) continue;

      if (message.type === "eos") {
        console.log("🎉 Recording completed!");
        break;
      } else if (message.type === "error") {
        console.error("❌ Recording error:", message.message);
        break;
      }
    }

    await pipeline.stop();

    // Verify file was created
    if (fs.existsSync(outputFile)) {
      const stats = fs.statSync(outputFile);
      console.log(`✅ File size: ${(stats.size / 1024 / 1024).toFixed(2)} MB`);
    }
  }
}

function generateFrame(frameNumber, width, height) {
  // Example: Generate animated colored frames
  const buffer = Buffer.alloc(width * height * 3);
  const red = (frameNumber * 5) % 256;
  const green = (frameNumber * 3) % 256;
  const blue = (frameNumber * 7) % 256;

  for (let i = 0; i < buffer.length; i += 3) {
    buffer[i] = red; // R
    buffer[i + 1] = green; // G
    buffer[i + 2] = blue; // B
  }

  return buffer;
}

// Usage
recordGeneratedVideoToFile();

Key Points for File Recording:

EOS is Required: Always call endOfStream() when done pushing data
OGV/Theora: Most reliable format for programmatic content
Non-live Mode: Set is-live: false for file-like behavior
Timestamping: Enable do-timestamp: true for proper timing
Error Handling: Monitor bus messages for completion and errors

Extracting Buffer Data with Pad Probes

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline(
  "videotestsrc ! videoconvert ! x264enc ! rtph264pay name=pay ! fakesink"
);
const payloader = pipeline.getElementByName("pay");

if (payloader) {
  // Add probe to capture comprehensive buffer data from pad
  const unsubscribe = payloader.addPadProbe("src", bufferData => {
    console.log("Buffer Data:", {
      // Raw buffer data
      buffer: bufferData.buffer, // Buffer object with raw data
      size: bufferData.buffer?.length, // Buffer size in bytes

      // Timing information (nanoseconds)
      pts: bufferData.pts, // Presentation timestamp
      dts: bufferData.dts, // Decode timestamp
      duration: bufferData.duration,
      offset: bufferData.offset,
      offsetEnd: bufferData.offsetEnd,

      // Buffer metadata
      flags: bufferData.flags, // GStreamer buffer flags

      // Stream format information
      caps: bufferData.caps, // Caps object with format details

      // RTP data (only for RTP streams)
      rtp: bufferData.rtp
        ? {
            timestamp: bufferData.rtp.timestamp,
            sequence: bufferData.rtp.sequence,
            ssrc: bufferData.rtp.ssrc,
            payloadType: bufferData.rtp.payloadType,
          }
        : undefined,
    });
  });

  await pipeline.play();

  // ... later, remove the probe
  unsubscribe();
  await pipeline.stop();
}

Pipeline State Management

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("videotestsrc ! autovideosink");

// State change operations return detailed results
const playResult = await pipeline.play();
console.log("Play result:", playResult.result); // 'success', 'async', 'failure', etc.
console.log("Current state:", playResult.finalState);

// Check if pipeline is playing
console.log("Is playing:", pipeline.playing());

// Pause and resume
await pipeline.pause();
await pipeline.play();

// Stop pipeline
await pipeline.stop();

Position and Duration Queries

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("videotestsrc ! timeoverlay ! autovideosink");
await pipeline.play();

setInterval(() => {
  const position = pipeline.queryPosition(); // Position in seconds
  const duration = pipeline.queryDuration(); // Duration in seconds
  console.log(`Position: ${position}s / Duration: ${duration}s`);
}, 1000);

Seeking

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("videotestsrc ! timeoverlay ! autovideosink");
await pipeline.play();

// Seek to 60 seconds
const seekSuccess = pipeline.seek(60);
console.log("Seek successful:", seekSuccess);

Message Bus Handling

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("videotestsrc num-buffers=100 ! autovideosink");
await pipeline.play();

// Listen for bus messages
while (true) {
  const message = await pipeline.busPop(1000); // 1 second timeout

  if (message) {
    console.log("Message:", message.type, message.srcElementName);

    if (message.type === "eos") {
      console.log("End of stream");
      break;
    } else if (message.type === "error") {
      console.error("Error:", message.errorMessage);
      break;
    }
  }
}

Element Property Manipulation

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline("videotestsrc name=source ! capsfilter name=filter ! autovideosink");

const source = pipeline.getElementByName("source");
const filter = pipeline.getElementByName("filter");

// Set various property types
source?.setElementProperty("pattern", "ball");
source?.setElementProperty("is-live", true);
source?.setElementProperty("num-buffers", 100);

filter?.setElementProperty("caps", "video/x-raw,width=1280,height=720,framerate=30/1");

// Get property values
const patternResult = source?.getElementProperty("pattern");
const capsResult = filter?.getElementProperty("caps");

// Access the actual values using the standardized format
const pattern = patternResult?.value;
const caps = capsResult?.value;

Pad Manipulation

import { Pipeline } from "gst-kit";

const pipeline = new Pipeline(
  "input-selector name=sel ! autovideosink videotestsrc pattern=0 ! sel.sink_0 videotestsrc pattern=1 ! sel.sink_1"
);

const selector = pipeline.getElementByName("sel");
await pipeline.play();

// Switch between input pads
setInterval(() => {
  const activePad = Math.random() > 0.5 ? "sink_0" : "sink_1";
  selector?.setPad("active-pad", activePad);
  console.log("Switched to:", activePad);
}, 2000);

// Get pad information
const srcPad = selector?.getPad("src");
console.log("Pad info:", srcPad?.name, srcPad?.direction, srcPad?.caps);

API Reference

Pipeline Class

class Pipeline {
  constructor(description: string);

  // Static methods
  static elementExists(elementName: string): boolean;

  // State management
  play(timeoutMs?: number): Promise<StateChangeResult>;
  pause(timeoutMs?: number): Promise<StateChangeResult>;
  stop(timeoutMs?: number): Promise<StateChangeResult>;
  playing(): boolean;

  // Element access
  getElementByName(name: string): Element | AppSinkElement | AppSrcElement | null;

  // Position and seeking
  queryPosition(): number;
  queryDuration(): number;
  seek(positionSeconds: number): boolean;

  // Message handling
  busPop(timeoutMs?: number): Promise<GstMessage | null>;
}

Element Types

// Base element with common functionality
interface Element {
  readonly type: "element";
  getElementProperty(key: string): GStreamerPropertyResult;
  setElementProperty(key: string, value: GStreamerPropertyValue): void;
  addPadProbe(padName: string, callback: (bufferData: BufferData) => void): () => void;
  setPad(attribute: string, padName: string): void;
  getPad(padName: string): GstPad | null;
}

// AppSink element for receiving data
interface AppSinkElement extends Element {
  readonly type: "app-sink-element";
  getSample(timeoutMs?: number): Promise<GStreamerSample | null>;
  onSample(callback: (sample: GStreamerSample) => void): () => void;
}

// AppSrc element for providing data
interface AppSrcElement extends Element {
  readonly type: "app-src-element";
  push(buffer: Buffer, pts?: Buffer | number): void;
  endOfStream(): void;
}

Buffer Flags Reference

import { GstBufferFlags } from "gst-kit";

// Check buffer flags
if (bufferData.flags & GstBufferFlags.GST_BUFFER_FLAG_DELTA_UNIT) {
  console.log("This is a delta frame (not a keyframe)");
}

if (bufferData.flags & GstBufferFlags.GST_BUFFER_FLAG_HEADER) {
  console.log("This buffer contains header data");
}

Available flags include:

GST_BUFFER_FLAG_LIVE: Buffer from live source
GST_BUFFER_FLAG_DECODE_ONLY: Buffer should only be decoded, not displayed
GST_BUFFER_FLAG_DISCONT: Buffer represents discontinuity
GST_BUFFER_FLAG_DELTA_UNIT: Buffer is delta unit (not keyframe)
GST_BUFFER_FLAG_HEADER: Buffer contains header information
And more...

Property System

Standardized Property Results

The getElementProperty() method returns a standardized object with type information:

// Property result format
const result = element.getElementProperty("property-name");

if (result === null) {
  console.log("Property value is null");
} else {
  console.log("Property type:", result.type); // "primitive" | "array" | "object" | "buffer" | "sample"
  console.log("Property value:", result.value); // The actual value
}

Property Types

primitive: strings, numbers, booleans, bigint (typically uint64s used to store nanoseconds)
array: Arrays of primitive values (strings, numbers, booleans, bigints)
object: GStreamer structures (like stats)
buffer: Raw binary data
sample: Media samples with buffer, caps, and metadata

Usage Examples

// String property
const patternResult = videotestsrc.getElementProperty("pattern");
if (patternResult?.type === "primitive") {
  console.log("Pattern:", patternResult.value); // e.g., "ball"
}

// Boolean property
const isLiveResult = videotestsrc.getElementProperty("is-live");
if (isLiveResult?.type === "primitive") {
  console.log("Is live:", isLiveResult.value); // true/false
}

// Structure/Object property (like stats)
const statsResult = rtpdepay.getElementProperty("stats");
if (statsResult?.type === "object") {
  const stats = statsResult.value;
  console.log("RTP timestamp:", stats.timestamp);
}

// Sample property
const sampleResult = fakesink.getElementProperty("last-sample");
if (sampleResult?.type === "sample") {
  const sample = sampleResult.value;
  console.log("Buffer size:", sample.buffer.length);
  console.log("Caps:", sample.caps);
}

Build System & Tools

Native Code (C++)

GYP: Cross-platform build configuration system
N-API: Node-API for runtime-independent native bindings
GStreamer Integration: Full integration with GStreamer 1.0 ecosystem
Compiler Support: GCC, Clang, MSVC with C++20 standard

TypeScript/JavaScript

Rollup: Module bundler generating both ESM and CJS outputs
TypeScript: Full type definitions and compilation
Dual Packaging: Supports both import and require statements
Source Maps: Full debugging support

Testing & Quality

Vitest: Modern, fast test runner with concurrent execution
ESLint: Code linting with TypeScript support
Prettier: Code formatting
Coverage: Built-in test coverage reporting

Project Structure

gst-kit/
├── src/
│   ├── cpp/                   # C++ native implementation
│   │   ├── addon.cpp          # N-API module entry point
│   │   ├── pipeline.cpp       # Pipeline class implementation
│   │   ├── element.cpp        # Element class implementation
│   │   ├── async-workers.cpp  # Async operation workers
│   │   └── type-conversion.cpp # Type conversion utilities
│   └── ts/                    # TypeScript implementation
│       ├── index.ts           # Main API exports and types
│       └── *.test.ts          # Comprehensive test suite
├── examples/                  # Usage examples
│   ├── basic-pipeline.mjs     # Simple pipeline example
│   ├── appsink.mjs           # AppSink usage
│   ├── appsrc.mjs            # AppSrc usage
│   ├── appsrc-eos.mjs        # AppSrc with end-of-stream
│   ├── record-to-file.mjs    # Recording to file example
│   ├── rtp-timestamp.mjs     # RTP handling
│   ├── bus.mjs               # Message bus handling
│   ├── seek.mjs              # Seeking functionality
│   ├── query.mjs             # Position/duration queries
│   ├── set-pad.mjs           # Pad manipulation
│   ├── fakesink.mjs          # Fakesink usage
│   └── glshader.mjs          # OpenGL shader example
├── build/                     # GYP build output
├── dist/                      # Rollup build output
│   ├── esm/                  # ES modules
│   ├── cjs/                  # CommonJS modules
│   └── index.d.ts            # Type definitions
├── scripts/                   # Build and utility scripts
├── binding.gyp               # GYP build configuration
├── rollup.config.mjs         # Rollup bundler configuration
├── vitest.config.ts          # Vitest test configuration
├── tsconfig.json             # TypeScript configuration
└── package.json              # Node.js package configuration

Performance Considerations

Concurrent Testing: All tests run concurrently for faster execution
Efficient Memory Management: Proper buffer lifecycle management
Async Operations: Non-blocking operations for better performance
Type Safety: Compile-time error detection reduces runtime overhead

Runtime Compatibility

Runtime	Support Level	Notes
Node.js 16+	✅ Full	Minimal version
Node.js 22+	✅ Full	Latest stable support
Bun 1.0+	✅ Full	Alternative runtime support
Deno	❌ Not supported	Native module limitations

Platform Compatibility

Platform	Local Development	Production Ready	Notes
Ubuntu/Linux	✅ Full	✅ Full	Excellent for servers
macOS	✅ Full	✅ Full	Intel and Apple Silicon
Windows	✅ Full	✅ Full	Requires environment setup
Docker	✅ Full	✅ Full	Ubuntu-based containers

License

MIT License - see LICENSE file for details.

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

Name		Name	Last commit message	Last commit date
Latest commit History 86 Commits
.github/workflows		.github/workflows
.vscode		.vscode
examples		examples
modules		modules
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
binding.gyp		binding.gyp
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
rollup.config.mjs		rollup.config.mjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

repugraf/gst-kit

Folders and files

Latest commit

History

Repository files navigation

GStreamer Kit

Project Goals & Modernization

Modern Runtime Support

Modern Build System

Enhanced Developer Experience

Complete Feature Set

Core Pipeline Features

Advanced Data Access

Media Processing

Runtime Features

Installation

System Requirements

Platform-Specific Installation Guide

Ubuntu/Debian (Recommended for Production)

Option A: Package Manager (Traditional)

Option B: Cross-Platform Setup with setup-cpp (Ubuntu)

macOS (Homebrew)

Option A: Homebrew (Traditional)

Option B: Cross-Platform Setup with setup-cpp (macOS)

Windows

Option A: Manual Installation

Option B: Cross-Platform Setup with setup-cpp (Recommended)

Common Installation Issues

Problem: "Cannot find gstreamer-1.0"

Problem: Missing plugins (playbin/decodebin errors)

Problem: "Permission denied" on Linux

Docker Installation

Quick Start

Basic Pipeline

Checking Element Availability

Working with AppSink (Pull-based Approach)

Working with AppSink (Event-Driven/Push Approach)

Working with AppSrc (Source Input)

Working with AppSrc for Custom Data Sources (with EOS)

Recording Programmatically Generated Streams to Files

Extracting Buffer Data with Pad Probes

Pipeline State Management

Position and Duration Queries

Seeking

Message Bus Handling

Element Property Manipulation

Pad Manipulation

API Reference

Pipeline Class

Element Types

Buffer Flags Reference

Property System

Standardized Property Results

Property Types

Usage Examples

Build System & Tools

Native Code (C++)

TypeScript/JavaScript

Testing & Quality

Project Structure

Performance Considerations

Runtime Compatibility

Platform Compatibility

License

Contributing

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages