VideoColorSpace.toJSON() — Methode · JavaScript-Referenz

Signatur

VideoColorSpace.prototype.toJSON()

Beschreibung

Die Methode toJSON() der Schnittstelle VideoColorSpace aus der WebCodecs-API ist ein Serializer. Sie wandelt das Farbraum-Objekt in ein einfaches JavaScript-Objekt um, das genau die vier Eigenschaften primaries, transfer, matrix und fullRange enthält. Dieses Objekt entspricht dem Dictionary VideoColorSpaceInit.

JSON.stringify() ruft toJSON() automatisch auf. Ohne diese Methode würde ein VideoColorSpace als leeres Objekt {} serialisiert, weil seine Eigenschaften als Getter am Prototyp liegen und nicht als eigene Eigenschaften der Instanz.

Typische Einsatzfälle:

Protokollieren und Debuggen: den Farbraum decodierter VideoFrame-Objekte ausgeben.
Weiterreichen: Farbraum-Informationen per postMessage() übertragen oder speichern.
Konfigurieren: das Ergebnis als colorSpace in einer VideoDecoderConfig oder im VideoFrame-Konstruktor verwenden.
Kopieren: mit new VideoColorSpace(cs.toJSON()) eine Kopie anlegen.

Rückgabewert

Typ

VideoColorSpaceInit ({ primaries: string|null, transfer: string|null, matrix: string|null, fullRange: boolean|null })

Beschreibung

Ein einfaches Objekt mit den vier Farbraum-Eigenschaften. Nicht gesetzte Werte erscheinen als null.

Beispiele

Farbraum anlegen und serialisieren

const cs = new VideoColorSpace({
  primaries: 'bt709',
  transfer: 'bt709',
  matrix: 'bt709',
  fullRange: false
});

console.log(cs.toJSON());
// JSON.stringify ruft toJSON() automatisch auf
console.log(JSON.stringify(cs));

{ primaries: 'bt709', transfer: 'bt709', matrix: 'bt709', fullRange: false } {"primaries":"bt709","transfer":"bt709","matrix":"bt709","fullRange":false}

Unvollständiger Farbraum: fehlende Felder werden null

const partial = new VideoColorSpace({ primaries: 'bt2020', transfer: 'pq' });
console.log(partial.toJSON());

{ primaries: 'bt2020', transfer: 'pq', matrix: null, fullRange: null }

Farbraum decodierter Frames protokollieren und an einen Worker senden

const worker = new Worker('analyse-worker.js');

const decoder = new VideoDecoder({
  output: (frame) => {
    // Serialisierbares Objekt statt VideoColorSpace-Instanz verschicken
    const colorSpace = frame.colorSpace.toJSON();
    console.log('Frame-Farbraum:', JSON.stringify(colorSpace));
    worker.postMessage({ timestamp: frame.timestamp, colorSpace });
    frame.close(); // Speicher sofort freigeben
  },
  error: (e) => console.error('Decoder-Fehler:', e)
});

decoder.configure({ codec: 'avc1.42E01E' });

Frame-Farbraum: {"primaries":"bt709","transfer":"bt709","matrix":"bt709","fullRange":false} (je nach Video unterschiedlich)

Farbraum kopieren und in einer Decoder-Konfiguration wiederverwenden

const original = new VideoColorSpace({
  primaries: 'smpte170m',
  transfer: 'smpte170m',
  matrix: 'smpte170m',
  fullRange: false
});

// Kopie über das Init-Dictionary
const copy = new VideoColorSpace(original.toJSON());
console.log(copy.matrix);

const config = {
  codec: 'vp8',
  colorSpace: original.toJSON()
};
const { supported } = await VideoDecoder.isConfigSupported(config);
console.log('Unterstützt:', supported);

smpte170m Unterstützt: true

// Wichtig · Fallstricke

Keine Rückumwandlung: Das Ergebnis ist ein einfaches Objekt und keine VideoColorSpace-Instanz. Nach JSON.parse() brauchst du new VideoColorSpace(obj), um wieder eine Instanz zu bekommen.
null-Werte: Nicht angegebene Felder werden als null serialisiert, nicht weggelassen. Frames ohne Farbraum-Angaben im Datenstrom können daher überall null liefern. Prüfe das, bevor du die Werte weiterverwendest.
Nur erlaubte Werte: Der Konstruktor akzeptiert nur feste Zeichenketten, zum Beispiel primaries: 'bt709', 'bt470bg', 'smpte170m', 'bt2020', 'smpte432'; transfer: 'bt709', 'smpte170m', 'iec61966-2-1', 'linear', 'pq', 'hlg'; matrix: 'rgb', 'bt709', 'bt470bg', 'smpte170m', 'bt2020-ncl'. Andere Werte lösen einen TypeError aus.
Kompatibilität: WebCodecs gibt es nur in sicheren Kontexten (HTTPS). Die API steht im Fenster und in Dedicated Workern zur Verfügung. Firefox unterstützt sie erst ab Version 130 und nur auf dem Desktop. Mit 'VideoColorSpace' in globalThis prüfst du, ob sie vorhanden ist.

Siehe auch

JSON.stringify() GeolocationCoordinates.toJSON() PaymentResponse.toJSON() Performance.toJSON() new VideoColorSpace()