@recappi/sdk

Platform support

Feature	macOS	Windows	Linux (x64 GNU)
decodeAudio / decodeAudioSync	Yes	Yes	Yes
ShareableContent.applications()	Yes	Yes	Yes
ShareableContent.applicationWithProcessId()	Yes	Yes	Yes
ShareableContent.onApplicationListChanged()	Yes	Yes	Yes (polling)
ShareableContent.isUsingMicrophone()	Yes	Yes	Yes (PulseAudio)
ShareableContent.onAppStateChanged()	Yes	Yes	Yes (polling)
ShareableContent.tapGlobalAudio()	Yes	Yes	Yes (PulseAudio monitor)
ShareableContent.tapAudio()	Yes	Yes	Yes (dedicated Pulse sink reroute)

Published Linux artifacts currently target x86_64-unknown-linux-gnu. The Linux implementation ships the same top-level ShareableContent surface as macOS and Windows, but it uses a PulseAudio-compatible userspace and shells out to pactl / ffmpeg, so capture requires those tools to be available at runtime.

If your application needs to choose a Linux fallback backend dynamically, use getPlatformCapabilities() instead of hard-coding platform checks. On Linux, those booleans reflect the currently reachable runtime prerequisites for each capture path, not just whether the functions are exported.

import { getPlatformCapabilities } from '@recappi/sdk'

const capabilities = getPlatformCapabilities()

if (capabilities.tapGlobalAudio) {
  console.log('Use Recappi for realtime capture')
} else {
  console.log('Use your Linux-specific fallback backend')
}

Usage

Recording system audio

Available on macOS, Windows, and Linux. Linux capture requires a PulseAudio-compatible server plus pactl and ffmpeg.

Both input and output devices are recording, mixed into a single audio stream.

import { writeFile } from 'node:fs/promises'
import { setTimeout } from 'node:timers/promises'

import { ShareableContent } from '@recappi/sdk'
import { createWavBuffer } from '@recappi/sdk/encode-wav'

const WavBuffers = []

let totalLength = 0

const session = ShareableContent.tapGlobalAudio([], (err, samples) => {
  if (err) {
    console.error('Error capturing audio:', err)
    return
  }
  WavBuffers.push(samples)
  totalLength += samples.length
})

console.info('Recording audio for 5 seconds...')

await setTimeout(5000) // Record for 5 seconds

session.stop()

console.info(`Recording stopped. Writing ${totalLength} samples to output.wav...`)

const { buf: contactedBuffer } = WavBuffers.reduce(
  ({ buf, offset }, cur) => {
    buf.set(cur, offset)
    return {
      buf,
      offset: offset + cur.length,
    }
  },
  {
    buf: new Float32Array(totalLength),
    offset: 0,
  },
)

console.log(`Creating WAV buffer ...`)

const wavBuffer = Buffer.from(
  createWavBuffer(contactedBuffer, {
    sampleRate: session.sampleRate,
    numChannels: session.channels,
  }),
)

await writeFile('output.wav', wavBuffer)

Listing running applications

Available on macOS, Windows, and Linux.

import { ShareableContent } from '@recappi/sdk'

const apps = ShareableContent.applications()

for (const app of apps) {
  console.log(`Name: ${app.name}, PID: ${app.processId}`)
}

Recording specific application

Available on macOS, Windows, and Linux. On Windows, tapAudio() currently uses the same capture backend as tapGlobalAudio() and does not isolate a single process stream yet. On Linux, tapAudio() reroutes matching Pulse sink-inputs into a dedicated capture sink and records that sink's monitor. This is best-effort and depends on the target application exposing movable Pulse streams.

import { ShareableContent } from '@recappi/sdk'

const apps = ShareableContent.applications()
const musicApp = apps.find((app) => app.name === 'Music')

if (musicApp) {
  const session = ShareableContent.tapAudio(musicApp.processId, (err, samples) => {
    if (err) {
      console.error('Error capturing audio:', err)
      return
    }
    // Process samples...
  })

  // Stop recording after 5 seconds
  setTimeout(() => {
    session.stop()
  }, 5000)
}

Playground

yarn install
yarn build
yarn workspace playground dev:server
yarn workspace playground dev:web

Local Linux Iteration From macOS

Use the bundled Docker environment to exercise the Linux backend locally from a macOS workstation.

bash ./scripts/test-linux-docker.sh

If you want an interactive shell inside the same Linux image:

bash ./scripts/docker-linux.sh bash

The Docker image installs Rust, Node.js, PulseAudio, pactl, and ffmpeg, so the Linux binding tests can run without depending on the host machine.