DataView.prototype.setInt16() — Methode · JavaScript-Referenz

Signatur

DataView.prototype.setInt16(byteOffset, value, littleEndian)

Beschreibung

setInt16() speichert einen Wert als vorzeichenbehaftete 16-Bit-Ganzzahl im Wertebereich von -32768 bis 32767 in den zugrunde liegenden ArrayBuffer. Anders als bei einem Int16Array legst du Position und Byte-Reihenfolge (Endianness) selbst fest. Der Offset muss außerdem nicht auf 2 Bytes ausgerichtet sein.

Typische Einsatzfälle sind Binärformate und Protokolle: WAV-Dateien mit 16-Bit-PCM-Samples, Netzwerkpakete, Dateikopfzeilen oder die Kommunikation mit WebSockets, WebUSB und WebSerial. Dort ist die Byte-Reihenfolge fest vorgegeben, unabhängig von der Plattform.

Der Wert wird zuerst mit ToNumber in eine Zahl umgewandelt und dann modulo 2¹⁶ abgeschnitten. Werte außerhalb des Bereichs führen also nicht zu einem Fehler, sondern laufen still über: Aus 32768 wird -32768. Nachkommastellen werden in Richtung null abgeschnitten, NaN und Infinity werden zu 0.

Ohne das dritte Argument schreibt die Methode im Big-Endian-Format, also mit dem höchstwertigen Byte zuerst. Für die meisten Dateiformate unter x86/ARM (z. B. WAV, BMP) brauchst du littleEndian = true.

Parameter

Name	Typ	Default	Beschreibung
$byteOffset Pflicht	number		Position in Bytes ab dem Anfang der View (nicht des Buffers!), an der geschrieben wird. Wird in eine Ganzzahl umgewandelt.
$value Pflicht	number		Der zu speichernde Wert. Er wird in eine Zahl umgewandelt und modulo 2¹⁶ in den Bereich `-32768` bis `32767` abgebildet.
$littleEndian	boolean	false	`true` schreibt im Little-Endian-Format, `false` oder `undefined` im Big-Endian-Format.

Beispiele

Grundlegende Nutzung und Byte-Reihenfolge

const buffer = new ArrayBuffer(4);
const view = new DataView(buffer);

view.setInt16(0, -2);        // Big-Endian (Standard)
view.setInt16(2, -2, true);  // Little-Endian

console.log(new Uint8Array(buffer));
console.log(view.getInt16(0), view.getInt16(2, true));

Uint8Array(4) [255, 254, 254, 255] -2 -2

Überlauf und Umwandlung von Werten

const view = new DataView(new ArrayBuffer(2));

const test = (v) => {
  view.setInt16(0, v);
  return view.getInt16(0);
};

console.log(test(32767));   // Maximum
console.log(test(32768));   // läuft über
console.log(test(-40000));  // läuft über
console.log(test(12.9));    // Nachkommastellen werden abgeschnitten
console.log(test(NaN));

32767 -32768 25536 12 0

16-Bit-PCM-Samples für eine WAV-Datei schreiben

// Float-Samples (-1..1) in 16-Bit-PCM (Little-Endian) umwandeln
const floatTo16BitPCM = (samples) => {
  const view = new DataView(new ArrayBuffer(samples.length * 2));
  samples.forEach((s, i) => {
    const clamped = Math.max(-1, Math.min(1, s)); // Überlauf vermeiden
    const int = clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff;
    view.setInt16(i * 2, int, true);
  });
  return view;
};

const pcm = floatTo16BitPCM([0, 0.5, -0.5, 1, -1]);
console.log(new Int16Array(pcm.buffer));

Int16Array(5) [0, 16383, -16384, 32767, -32768]

// Wichtig · Fallstricke

RangeError: Die Methode wirft einen Fehler, wenn byteOffset + 2 über die Länge der View hinausgeht oder der Offset negativ ist.
Standard ist Big-Endian: Wenn du littleEndian vergisst, entstehen bei Formaten wie WAV oder BMP falsche Daten. Das ist ein häufiger Fehler.
Stiller Überlauf: Werte außerhalb von -32768 bis 32767 werden ohne Warnung umgebrochen. Begrenze sie vorher selbst, z. B. mit Math.max/Math.min.
BigInt wird nicht akzeptiert und löst einen TypeError aus. Für 64-Bit-Werte gibt es setBigInt64().
Der Offset bezieht sich auf den Anfang der View. Wurde sie mit einem eigenen byteOffset erzeugt, wird dieser noch hinzugerechnet.
Ist der ArrayBuffer abgelöst (detached), etwa nach einem postMessage-Transfer, wirft die Methode einen TypeError.
Kompatibilität: Die Methode wird in allen modernen Browsern und in Node.js unterstützt.

Siehe auch

DataView DataView.prototype.getInt16() DataView.prototype.setUint16() DataView.prototype.setInt32() Int16Array ArrayBuffer