SDK-Referenz

Alle Beispiele gehen von einer Instanz aus:

const pixl = new Pixl({ key: 'pixl_DEIN_SCHLÜSSEL' });

Optionen des Konstruktors stehen unter Installation.

EventsLink zur Überschrift kopieren

pixl.on(event, handler)Link zur Überschrift kopieren

Registriert einen Handler für einen Event-Typ. Mit '*' bekommst du alle Events. Gibt die Instanz zurück, Aufrufe lassen sich also verketten.

pixl
  .on('twitch.cheer', (data) => console.log(`${data.username}: ${data.bits} Bits`))
  .on('*', (data, event) => console.log(event.event, data));

Der Handler bekommt zwei Argumente:

event.replay ist true, wenn jemand das Event im Dashboard erneut abgespielt hat. Willst du Replays ignorieren, prüf darauf. id und at (ISO-Zeitpunkt) gibt es nur bei Events, die auch im Eventlog stehen. history setzt nur feed().

pixl.off(event, handler)Link zur Überschrift kopieren

Entfernt einen Handler wieder. Du musst dieselbe Funktion übergeben wie bei on().

pixl.events(query?)Link zur Überschrift kopieren

Fragt das Eventlog ab, neueste Events zuerst. Gibt ein Promise zurück.

const { events, nextCursor } = await pixl.events({
  since: 'stream',
  types: ['twitch.sub', 'twitch.sub_gift'],
  limit: 20,
});

// Nächste Seite
const page2 = await pixl.events({ since: 'stream', cursor: nextCursor });

Ergebnis: { events: { id, event, data, at }[], nextCursor: string | null }.

pixl.fetchAllEvents(query?)Link zur Überschrift kopieren

Wie events(), holt aber alle Seiten nacheinander und gibt die Events älteste zuerst zurück. Kennt since, until und types.

const cheers = await pixl.fetchAllEvents({ since: 'stream', types: ['twitch.cheer'] });

pixl.feed(options, handler)Link zur Überschrift kopieren

Erst alle Events seit since, danach live, jedes genau einmal. Ausführlich unter Historie + live.

pixl.feed({ since: 'stream', types: ['twitch.cheer'] }, (data, event) => {
  console.log(event.history ? 'bisher' : 'neu', data.bits);
});

KanalLink zur Überschrift kopieren

pixl.org()Link zur Überschrift kopieren

Infos zum Kanal, dem der Schlüssel gehört, und welche Rechte er hat: { id, name, logo, twitchChannelLogin, scopes }. Praktisch, um zu prüfen, ob ein Schlüssel funktioniert.

SubsLink zur Überschrift kopieren

pixl.subs()Link zur Überschrift kopieren

Aktuelle Sub-Zahl direkt von Twitch, unabhängig vom Eventlog: { total, points, at }. Braucht subs:read. Änderungen kommen live als subs.updated mit denselben Feldern, Details unter GET /subs.

const show = ({ total }) => (el.textContent = total);
pixl.subs().then(show);
pixl.on("subs.updated", show);

MusikLink zur Überschrift kopieren

pixl.nowPlaying()Link zur Überschrift kopieren

Was gerade auf Spotify läuft: { playing, progressMs, at, track, addedBy }. Braucht spotify:read und das Modul Musik. Ohne aktives Gerät ist track null. Änderungen kommen live als spotify.now_playing mit denselben Feldern, Details unter GET /spotify/now-playing.

Pixl.progress(nowPlaying, now?)Link zur Überschrift kopieren

Fortschritt in Millisekunden zum Zeitpunkt now (Standard: jetzt). Läuft der Song, rechnet es ab at weiter, höchstens bis zur Songlänge. Damit läuft ein Fortschrittsbalken flüssig, ohne dass pixl jede Sekunde etwas schicken muss.

let current = null;
const show = (np) => {
  current = np;
  title.textContent = np.track ? `${np.track.name} · ${np.track.artists.join(", ")}` : "";
  cover.src = np.track?.image ?? "";
};
pixl.nowPlaying().then(show);
pixl.on("spotify.now_playing", show);

setInterval(() => {
  if (current?.track) bar.style.width = `${(Pixl.progress(current) / current.track.durationMs) * 100}%`;
}, 250);

StreamElementsLink zur Überschrift kopieren

pixl.streamElements(path, params?)Link zur Überschrift kopieren

Fragt Daten aus dem verbundenen StreamElements-Kanal ab, z.B. pixl.streamElements('sessions') oder pixl.streamElements('points/top', { limit: 10 }). Braucht streamelements:read. Erlaubte Pfade und was dahinter steckt: GET /streamelements/{pfad}. Die Antwort kommt unverändert von StreamElements.

TTSLink zur Überschrift kopieren

pixl.tts.player(options?)Link zur Überschrift kopieren

Spielt jedes vorgelesene tts.ready der Reihe nach ab und hält sich an „Überspringen“ aus dem Dashboard. Braucht tts:read. Optionen und Beispiele unter TTS.

pixl.tts.speak(text, { voice?, filters? })Link zur Überschrift kopieren

Lässt einen Text vorlesen, abgespielt wird er dann in jedem Overlay mit Player. filters: false oder z.B. { links: false } schaltet Filter ab, siehe TTS. Braucht tts:write und verbraucht Credits des Kanals. Gibt { id, text, voice } zurück.

pixl.tts.voices() / pixl.tts.audio(id) / pixl.tts.marks(id)Link zur Überschrift kopieren

Verfügbare Stimmen samt Standardstimme des Kanals, das Audio eines Eintrags als Blob (MP3) bzw. seine Zeitmarken pro Wort ([{ word, start, end }], kosten beim ersten Abruf extra).

VerbindungLink zur Überschrift kopieren

pixl.statusLink zur Überschrift kopieren

Aktueller Verbindungsstatus:

pixl.onStatus(handler)Link zur Überschrift kopieren

Ruft handler sofort mit dem aktuellen Status auf und danach bei jedem Wechsel. Gibt eine Funktion zum Abmelden zurück.

pixl.onStatus((status) => {
  document.body.classList.toggle('offline', status !== 'connected');
});

pixl.connect() / pixl.disconnect()Link zur Überschrift kopieren

Startet bzw. beendet die Live-Verbindung. Nach Abbrüchen verbindet das SDK automatisch neu, erst nach einer halben Sekunde, dann mit wachsendem Abstand bis höchstens 30 Sekunden.

pixl.request(path, params?)Link zur Überschrift kopieren

Rohzugriff auf einen Endpunkt der HTTP-API, z.B. pixl.request('/events', { limit: '5' }). Für Fälle, die die anderen Funktionen noch nicht abdecken.

FehlerLink zur Überschrift kopieren

HTTP-Funktionen werfen bei Fehlern einen PixlApiError mit status (HTTP-Code) und message, bei TTS zusätzlich problem. 403 heißt, dem Schlüssel fehlt ein Recht:

try {
  await pixl.events({ since: 'stream' });
} catch (e) {
  if (e.status === 404) console.log('Noch kein Stream gelaufen');
}

Fehler in deinen eigenen Handlern landen in der Konsole, brechen aber die Verbindung nicht ab.