# SDK-Referenz (https://docs.pixl.lennox.zip/sdk/reference)

> Alle Funktionen der Pixl-Klasse

Alle Beispiele gehen von einer Instanz aus:

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

Optionen des Konstruktors stehen unter [Installation](/sdk/installation#optionen).

## Events [#events]

### `pixl.on(event, handler)` [#pixlonevent-handler]

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

```js
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:

| Argument | Inhalt |
|---|---|
| `data` | Daten des Events, siehe [Event-Referenz](/sdk/events#event-referenz) |
| `event` | Das ganze Event: `{ event, data, replay, id?, at?, history? }` |

`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()`](/sdk/feed).

### `pixl.off(event, handler)` [#pixloffevent-handler]

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

### `pixl.events(query?)` [#pixleventsquery]

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

```js
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 });
```

| Feld | Typ | Bedeutung |
|---|---|---|
| `since` | `Date`, ISO-String, Unix-ms oder `'stream'` | Ab wann. `'stream'` = Start des letzten Streams |
| `until` | `Date`, ISO-String oder Unix-ms | Bis wann (exklusiv) |
| `types` | `string[]` | Nur diese Event-Typen |
| `limit` | `number` | 1 bis 200, Standard 50 |
| `cursor` | `string` | `nextCursor` der vorherigen Seite |

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

<Callout>
  Im Eventlog stehen nur die Events, die pixl speichert (siehe [Event-Referenz](/sdk/events#event-referenz)). Reine Live-Events wie Chat-Nachrichten oder Zwischenstände von Umfragen bekommst du nur über `pixl.on()`.
</Callout>

### `pixl.fetchAllEvents(query?)` [#pixlfetchalleventsquery]

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

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

### `pixl.feed(options, handler)` [#pixlfeedoptions-handler]

Erst alle Events seit `since`, danach live, jedes genau einmal. Ausführlich unter [Historie + live](/sdk/feed).

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

## Kanal [#kanal]

### `pixl.org()` [#pixlorg]

Infos zum Kanal, dem der Schlüssel gehört, und welche [Rechte](/sdk/api-keys#rechte) er hat: `{ id, name, logo, twitchChannelLogin, scopes }`. Praktisch, um zu prüfen, ob ein Schlüssel funktioniert.

## Subs [#subs]

### `pixl.subs()` [#pixlsubs]

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`](/sdk/api#get-subs).

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

## Musik [#musik]

### `pixl.nowPlaying()` [#pixlnowplaying]

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`](/sdk/api#get-spotifynow-playing).

### `Pixl.progress(nowPlaying, now?)` [#pixlprogressnowplaying-now]

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.

```js
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);
```

## StreamElements [#streamelements]

### `pixl.streamElements(path, params?)` [#pixlstreamelementspath-params]

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}`](/sdk/api#get-streamelementspfad). Die Antwort kommt unverändert von StreamElements.

## TTS [#tts]

### `pixl.tts.player(options?)` [#pixlttsplayeroptions]

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](/sdk/tts#abspielen-im-overlay).

### `pixl.tts.speak(text, { voice?, filters? })` [#pixlttsspeaktext--voice-filters-]

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](/sdk/tts#selbst-vorlesen-lassen). 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)` [#pixlttsvoices--pixlttsaudioid--pixlttsmarksid]

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).

## Verbindung [#verbindung]

### `pixl.status` [#pixlstatus]

Aktueller Verbindungsstatus:

| Status | Bedeutung |
|---|---|
| `connecting` | Verbindung wird aufgebaut, auch beim Neuverbinden |
| `connected` | Live-Verbindung steht |
| `disconnected` | Verbindung weg, das SDK versucht es gleich wieder, auch während pixl gerade aktualisiert wird (spätestens alle 10 Sekunden) |
| `unauthorized` | Schlüssel ungültig oder gelöscht. Es wird nicht neu verbunden |
| `closed` | Mit `disconnect()` beendet, oder noch nicht gestartet |

### `pixl.onStatus(handler)` [#pixlonstatushandler]

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

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

### `pixl.connect()` / `pixl.disconnect()` [#pixlconnect--pixldisconnect]

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?)` [#pixlrequestpath-params]

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

## Fehler [#fehler]

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](/sdk/api-keys#rechte):

```js
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.