Project setup

1. Copy the source/ directory into your project, e.g. src/janode/.

2. Ensure your package.json includes "type": "module" or your bundler handles ESM, because all source files use import/export syntax.

3. If using TypeScript, add a path alias in tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "janode": ["src/janode/janode.js"],
      "janode/plugins/*": ["src/janode/plugins/*"]
    },
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

4. Set environment variables consumed by your app (none are required by the library itself — connection credentials are passed programmatically).

5. If using Babel, ensure @babel/plugin-transform-modules-commonjs or equivalent is configured so ESM imports resolve.

6. For production deployments that only use WebSockets, you may stub unix-dgram if native compilation is unavailable:

// package.json
"browser": {
  "unix-dgram": false
}

Public API

Janode.connect

import Janode from './janode/janode.js';

function connect(config: {
  is_admin: boolean;
  address: {
    url: string;          // ws://, wss://, file:// (unix)
    apisecret?: string;
  } | Array<{ url: string; apisecret?: string }>;
  retry_time_secs?: number;
  max_retries?: number;
}): Promise<Connection>

The primary entry point. Call it once at startup to obtain a Connection. Pass is_admin: true to target the Janus Admin API port. Pass multiple entries in address for failover across Janus nodes.

Connection.create

// on a Connection instance returned by Janode.connect()
connection.create(): Promise<Session>

Creates a Janus session over the established connection. One connection can hold multiple sessions. Call this before attaching any plugin handles. The returned Session emits events such as JANODE.EVENT.SESSION_DESTROYED.

Session.attach

// on a Session instance returned by connection.create()
session.attach(pluginDescriptor: {
  id: string;          // Janus plugin identifier string
  Handle: typeof Handle;
}): Promise<Handle>

Attaches to a Janus plugin and returns a typed handle. Pass a plugin module's exported descriptor (e.g. EchoTestPlugin, VideoRoomPlugin). The returned handle exposes plugin-specific methods and emits plugin-specific events. Always await handle.detach() when done.

Handle (base class)

// extended by every plugin handle
class Handle extends EventEmitter {
  id: number;
  session: Session;
  detach(): Promise<void>;
  hangup(): Promise<void>;
  // plugin-specific methods defined in each plugin file
}

The base class for all plugin handles. Users extending Janode with custom plugins must subclass Handle and override handleMessage. Subscribe to Janode.EVENT.HANDLE_WEBRTCUP, HANDLE_HANGUP, HANDLE_MEDIA, HANDLE_SLOWLINK, and HANDLE_DETACHED for WebRTC lifecycle events.

Working examples

Scenario - Basic EchoTest signaling

Establish a WebSocket connection to Janus, create a session, attach the EchoTest plugin, send an offer, and receive an answer. This is the minimal integration path for testing connectivity.

import Janode from './janode/janode.js';
import EchoTestPlugin from './janode/plugins/echotest-plugin.js';

const { Logger } = Janode;

async function runEchoTest(offerSdp: string) {
  const connection = await Janode.connect({
    is_admin: false,
    address: { url: 'ws://127.0.0.1:8188/', apisecret: 'secret' },
  });

  const session = await connection.create();
  const echoHandle = await session.attach(EchoTestPlugin);

  echoHandle.on(Janode.EVENT.HANDLE_WEBRTCUP, () => Logger.info('WebRTC up'));
  echoHandle.on(Janode.EVENT.HANDLE_HANGUP, (data: unknown) => Logger.info('hangup', data));

  // EchoTestPlugin exposes a start() method
  const { jsep: answerSdp } = await (echoHandle as any).start({
    video: true,
    audio: true,
    jsep: { type: 'offer', sdp: offerSdp },
  });

  Logger.info('Got answer SDP', answerSdp);

  await echoHandle.detach();
  await session.destroy();
  await connection.close();

  return answerSdp;
}

Scenario - Admin API: list active sessions

Use the Admin API port to inspect Janus server state without creating media sessions. Useful for health checks or monitoring dashboards.

import Janode from './janode/janode.js';

async function listJanusSessions(): Promise<unknown[]> {
  const admin = await Janode.connect({
    is_admin: true,
    address: { url: 'ws://127.0.0.1:7188/', apisecret: 'secret' },
  });

  const sessions = await (admin as any).listSessions();
  console.log('Active sessions:', sessions);

  await (admin as any).close();
  return sessions;
}

Scenario - VideoRoom publish/subscribe

Attach to the VideoRoom plugin to create a room and join as a publisher. Demonstrates plugin-specific methods and event subscriptions.

import Janode from './janode/janode.js';
import VideoRoomPlugin from './janode/plugins/videoroom-plugin.js';

async function publishToVideoRoom(offerSdp: string, roomId: number) {
  const connection = await Janode.connect({
    is_admin: false,
    address: { url: 'ws://127.0.0.1:8188/', apisecret: 'secret' },
  });

  const session = await connection.create();
  const vrHandle = await session.attach(VideoRoomPlugin);

  // VideoRoomPlugin exposes join(), publish(), etc.
  await (vrHandle as any).joinPublisher({ room: roomId, display: 'Node Publisher' });

  vrHandle.on((VideoRoomPlugin as any).EVENT.VIDEOROOM_DESTROYED, () =>
    console.log('Room destroyed')
  );

  const { jsep: answer } = await (vrHandle as any).publish({
    jsep: { type: 'offer', sdp: offerSdp },
  });

  console.log('Publishing, answer SDP:', answer);
  return { vrHandle, session, connection };
}

File walkthrough

• janode.js - Exports the Janode default object with connect(), EVENT constants, and Logger. This is the only file consumers import directly from the core.
• connection.js - Connection class wrapping a transport instance. Handles session map, transaction correlation, and reconnection logic.
• session.js - Session class. Owns keepalive timers, handle registry, and routes incoming Janus messages to the correct handle.
• handle.js - Handle base class that plugin handles inherit. Contains transaction dispatch, message routing, and detach logic.
• protocol.js - String constants for Janus message types (janus, ack, event, etc.) and type-guard helpers (isAckData, isErrorData, isResponseData).
• configuration.js - Validates and normalizes the config object passed to connect(). Internal use only.
• tmanager.js - TransactionManager maps outgoing transaction IDs to pending promise resolvers.
• transport-ws.js - WebSocket transport with ping/pong keepalives and configurable retry logic.
• transport-unix.js - Unix DGRAM socket transport; binds a local socket at /tmp/.janode-<id>.
• utils/logger.js - Simple leveled logger (verbose, info, warn, error) accessible as Janode.Logger.
• utils/utils.js - getNumericID, checkUrl, newIterator, delayOp — internal helpers.
• plugins/ - One file per supported Janus plugin. Each exports a plugin descriptor { id, Handle } and plugin-specific EVENT constants.

Common pitfalls and fixes

• unix-dgram fails to build on CI/Docker — Install build-essential (Linux) or ensure Xcode CLT is present; or set "unix-dgram": false in package.json browser field if you only use WS transport.
• ESM import errors (ERR_REQUIRE_ESM) — The source uses import/export; set "type": "module" in your package.json or use .mjs extensions; do not require() these files.
• TypeScript cannot find plugin modules — Add "janode/plugins/*": ["src/janode/plugins/*"] to tsconfig.json paths and ensure moduleResolution is NodeNext or Bundler.
• Janus apisecret mismatch causes all requests to return 403 — The apisecret in your config must exactly match the api_secret value in janus.jcfg.
• Handle events not firing — Verify the session keepalive interval (ka_interval) is shorter than Janus's session_timeout; the default is 30 s but Janus default timeout is also 60 s.
• Connection silently drops and never reconnects — Set max_retries and retry_time_secs explicitly in connect() config; the defaults may not match your infrastructure's restart latency.

Vibe-coding prompt template

I have dropped the Janode source library into `src/janode/` in my Node.js project.
The upstream npm package is `user@example.com`. The integration guide is in `USAGE.md`.

Please help me integrate it step by step:

1. Read `USAGE.md` and `src/janode/janode.js` to understand the public API.
2. Install all required dependencies listed in `USAGE.md`.
3. Create a `src/janusService.ts` module that:
   - Connects to Janus at the URL stored in the `JANUS_URL` env var using `Janode.connect()`.
   - Creates a session and exposes `getSession()`.
   - Attaches to the VideoRoom plugin (`src/janode/plugins/videoroom-plugin.js`) and exposes `getVideoRoomHandle()`.
   - Gracefully closes the connection on process exit.
4. Wire the service into my existing Express app in `src/server.ts`.
5. Add TypeScript types where the library does not provide them (use `any` sparingly).
6. Show me how to subscribe to `Janode.EVENT.HANDLE_WEBRTCUP` and `HANDLE_HANGUP` events.

Only use APIs visible in `USAGE.md` and the source files under `src/janode/`. Do not invent method names.

License and credit

The upstream library is published under the MIT License by Meetecho s.r.l. See source/LICENSE if present, or refer to the npm package page and the GitHub repository for the full license text. This AVCP block redistributes the source of user@example.com unmodified.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Self-Hosted WebRTC P2P Video Conferencing Platform

PHP, Laravel & Business Scripts

Free