@hadidyapp/audio-live

Live streaming SDK for the Hadidy Audio platform. Covers session management, WHIP/RTMPS encoder setup, LiveKit WebRTC multi-source rooms, HLS/WHEP playback, and real-time SSE session state.

Installation

npm install @hadidyapp/audio-live

Dependencies: hls.js and livekit-client are bundled — no separate install needed. Requires @hadidyapp/audio-sdk ^0.1.2 (installed automatically as a peer dependency).

Single-source broadcast — WHIP (OBS 30+ / Larix)

WHIP is the recommended protocol. The full ingest URL (including stream key) is returned by the API — paste it directly into your encoder.

import { LiveClient, SessionState } from '@hadidyapp/audio-live';

const live = new LiveClient({ apiKey: 'had_live_...' });

const session = await live.sessions.createSession({
  title: 'Friday Night Show',
  ingest_protocol: 'whip',   // default; can be omitted
  recording_enabled: true,
});
await live.sessions.startSession(session.id);

console.log('WHIP endpoint:', session.ingest_url);
// → https://ingest.hadidy.com/{stream_key}/whip

// OBS 30+: Settings → Stream → Service: WHIP
//   Server: paste session.ingest_url  (no separate stream key field)
// Larix Broadcaster: tap +, pick WHIP, paste session.ingest_url

Single-source broadcast — RTMPS (OBS older / vMix / Streamlabs)

For encoders that don't support WHIP, use RTMPS. The server address and stream key are separate fields.

const session = await live.sessions.createSession({
  title: 'Friday Night Show',
  ingest_protocol: 'rtmp',   // TLS-encrypted on port 4936 externally
  recording_enabled: true,
});
await live.sessions.startSession(session.id);

console.log('RTMPS server:', session.ingest_url);  // rtmps://rtmps.hadidy.com:4936/
console.log('Stream key:  ', session.stream_key);

// OBS (any version): Settings → Stream → Service: Custom
//   Server:     paste session.ingest_url  (rtmps://…)
//   Stream Key: paste session.stream_key
//
// vMix / Streamlabs: use the same server + key fields

Track metadata — push current track to listeners

Call updateNowPlaying whenever the track changes. Also push the upcoming track so listeners' players can preload the cover art before the transition.

// On track change in your DJ app:
await live.sessions.updateNowPlaying(session.id, {
  title: 'Midnight City',
  artist: 'M83',
  album: 'Hurry Up, We\'re Dreaming',
  cover_url: 'https://i.ytimg.com/vi/dX3k_QDnzHE/maxresdefault.jpg',

  // Optional: preload next track on listeners' devices
  next_title: 'Resonance',
  next_artist: 'Home',
  next_cover_url: 'https://example.com/next-cover.jpg',
});

// Clear track info (e.g. between sets)
await live.sessions.clearNowPlaying(session.id);

Note on cover_url: must be a valid https:// URL. YouTube thumbnail URLs are accepted only when the video ID is a real 11-character YouTube ID — local file paths passed as video IDs are rejected automatically.

Real-time session state (SSE)

Subscribe to live updates pushed from the server — no polling needed.

import { SessionState } from '@hadidyapp/audio-live';

const state = new SessionState({ sessionId: session.id, apiKey: 'had_live_...' });

state.on('status',      (s) => console.log('Stream status:', s));       // 'live' | 'stopped' | …
state.on('listeners',   (n) => console.log(`${n} listeners`));
state.on('now-playing', (track) => {
  if (track) console.log(`▶ ${track.artist} — ${track.title}`);
  else       console.log('No track info');
});
state.on('next-track',  (track) => {
  // Fires when the DJ pushes next_title/next_cover_url.
  // Use this to preload the cover image before the transition:
  if (track?.cover_url) {
    const img = new Image();
    img.src = track.cover_url;   // warms browser cache
  }
});
state.on('error',       (err) => console.error('SSE error:', err));

state.subscribe();

// When done
state.unsubscribe();

| Event | Payload | When | |---|---|---| | status | string | Session state changes (created, live, stopped, …) | | listeners | number | Listener count updates | | now-playing | NowPlayingInfo \| null | DJ pushes a track change | | next-track | { title, artist, cover_url } \| null | DJ pushes upcoming track | | error | Error | SSE connection error |

HLS Listener

Stream playback via LL-HLS (Low-Latency HLS). Latency is ~4–5 seconds end-to-end.

import { LiveClient, HLSPlayer } from '@hadidyapp/audio-live';

const live = new LiveClient({ apiKey: 'had_live_...' });
const session = await live.sessions.getSession(sessionId);

const player = new HLSPlayer({
  hlsUrl: session.playback_url!,         // https://live.hadidy.com/{key}/index.m3u8
  videoElement: document.querySelector('audio')!,
  autoplay: true,
});

player.on('state-change', (state) => console.log('Player:', state));
// states: 'idle' | 'loading' | 'playing' | 'paused' | 'error'

Sub-500ms latency (WebRTC): use the WHEP endpoint instead of HLS for near-real-time playback with no buffering:

https://ingest.hadidy.com/{stream_key}/whep

Pass this URL to an RTCPeerConnection with a WHEP client, or use a player that supports WHEP natively (e.g. VLC 4, OBS 30+ monitor).

Multi-source WebRTC room

Host interactive sessions with multiple speakers via LiveKit.

import { LiveClient, LiveRoom } from '@hadidyapp/audio-live';

const live = new LiveClient({ apiKey: 'had_live_...' });

// Create a multi-speaker session
const session = await live.sessions.createSession({
  mode: 'multi',
  max_speakers: 4,
});
await live.sessions.startSession(session.id);

// Add a speaker — returns a short-lived participant token
const source = await live.sessions.createSource(session.id, {
  role: 'speaker',
  display_name: 'Ahmed',
});

// Connect and publish microphone
const room = new LiveRoom({
  livekitUrl: 'wss://livekit.hadidy.com',   // your LiveKit server, NOT session.ingest_url
  participantToken: source.participant_token!,
});
await room.connect();
await room.publishMicrophone();

room.on('participant-joined', (p) => console.log(`${p.identity} joined`));
room.on('participant-left',   (p) => console.log(`${p.identity} left`));
room.on('disconnected',       ()  => console.log('Disconnected from room'));

// When done
await room.unpublishMicrophone();
await room.disconnect();

API

LiveClient

All session methods are on live.sessions.*:

| Method | Description | |---|---| | createSession(options?) | Create a new session (WHIP by default) | | getSession(id) | Fetch a session by ID | | listSessions(params?) | Paginated session list | | listSessionsAll() | Async iterator over all sessions | | updateSession(id, options) | Update title, recording flag, etc. (before going live) | | startSession(id) | Transition to starting state | | stopSession(id) | End the session | | restartSession(id) | Reuse key/settings from a previously ended session | | deleteSession(id) | Permanently delete | | regenerateKey(id) | Rotate stream key (session must not be live) | | updateNowPlaying(id, update) | Push current + next track metadata | | clearNowPlaying(id) | Wipe track info | | createSource(sessionId, options) | Add a speaker to a multi-source room | | listSources(sessionId) | List active speakers | | listParticipants(sessionId) | List LiveKit participants | | listRecordings(sessionId) | List finished recordings with download URLs |

LiveRoom

| Method | Description | |---|---| | connect() | Join the LiveKit room | | disconnect() | Leave the room | | publishMicrophone() | Publish local mic as an audio track | | unpublishMicrophone() | Stop publishing |

Events: participant-joined, participant-left, track-subscribed, disconnected.

HLSPlayer

| Method | Description | |---|---| | play() / pause() | Playback control | | destroy() | Tear down hls.js instance |

Events: state-change.

SessionState

| Method | Description | |---|---| | subscribe() | Open SSE connection | | unsubscribe() | Close connection | | on(event, handler) | Attach event listener |

License

MIT