Revision 927229 of SourceBuffer

<p>{{APIRef("Media Source Extensions")}}{{SeeCompatTable}}{{draft}}</p>

<p>The <strong><code>SourceBuffer</code></strong> interface represents a chunk of media to be passed into an {{domxref("HTMLMediaElement")}} and played, via a <code>MediaSource</code> object. This can be made up of one or several media segments.</p>

<h2 id="Properties">Properties</h2>

<p><em>Inherits properties from its parent interface, {{domxref("EventTarget")}}.</em></p>

<dl>
 <dt>{{domxref("SourceBuffer.mode")}}</dt>
 <dd>Controls how the order of media segments in the <code>SourceBuffer</code> is handled, in terms of whether they can be appended in any order, or they have to be kept in a strict sequence.</dd>
 <dt>{{domxref("SourceBuffer.updating")}} {{readonlyInline}}</dt>
 <dd>Indicates whether the <code>SourceBuffer</code> is currently being updated — i.e. whether an {{domxref("SourceBuffer.appendBuffer()")}}, {{domxref("SourceBuffer.appendStream()")}}, or {{domxref("SourceBuffer.remove()")}} operation is currently in progress.</dd>
 <dt>{{domxref("SourceBuffer.buffered")}} {{readonlyInline}}</dt>
 <dd>Returns the time ranges that are currently buffered in the <code>SourceBuffer</code>.</dd>
 <dt>{{domxref("SourceBuffer.timestampOffset")}}</dt>
 <dd>Controls the offset applied to timestamps inside media segments that are subsequently appended to the <code>SourceBuffer</code>.</dd>
 <dt>{{domxref("SourceBuffer.audioTracks")}} {{readonlyInline}}</dt>
 <dd>A list of the audio tracks currently contained inside the <code>SourceBuffer</code>.</dd>
 <dt>{{domxref("SourceBuffer.videoTracks")}} {{readonlyInline}}</dt>
 <dd>A list of the video tracks currently contained inside the <code>SourceBuffer</code>.</dd>
 <dt>{{domxref("SourceBuffer.textTracks")}} {{readonlyInline}}</dt>
 <dd>A list of the text tracks currently contained inside the <code>SourceBuffer</code>.</dd>
 <dt>{{domxref("SourceBuffer.appendWindowStart")}}</dt>
 <dd>Controls the timestamp for the start of the <a href="https://w3c.github.io/media-source/#append-window">append window</a>. This is a timestamp range that can be used to filter what media data is appended to the <code>SourceBuffer</code>. Coded media frames with timestamps wthin this range will be appended, whereas those outside the range will be filtered out.</dd>
 <dt>{{domxref("SourceBuffer.appendWindowEnd")}}</dt>
 <dd>Controls the timestamp for the end of the append window.</dd>
 <dt>{{domxref("SourceBuffer.trackDefaults")}}</dt>
 <dd>Specifies the default values to use if kind, label, and/or language information is not available in the <a href="https://w3c.github.io/media-source/#init-segment">initialization segment</a> of the media to be appended to the <code>SourceBuffer</code>.</dd>
</dl>

<dl>
</dl>

<dl>
</dl>

<h2 id="Methods">Methods</h2>

<p><em>Inherits properties from its parent interface, {{domxref("EventTarget")}}.</em></p>

<dl>
 <dt>{{domxref("SourceBuffer.appendBuffer()")}}</dt>
 <dd>Appends media segment data from an {{domxref("ArrayBuffer")}} or <code>ArrayBufferView</code> object to the <code>SourceBuffer</code>.</dd>
 <dt>{{domxref("SourceBuffer.appendStream()")}}</dt>
 <dd>Appends media segment data from a <code>ReadableStream</code> object to the <code>SourceBuffer</code>.</dd>
 <dt>{{domxref("SourceBuffer.abort()")}}</dt>
 <dd>Aborts the current segment and resets the segment parser.</dd>
 <dt>{{domxref("SourceBuffer.remove()")}}</dt>
 <dd>Removes media segments within a specific time range from the <code>SourceBuffer</code>.</dd>
</dl>

<h2 id="Examples">Examples</h2>

<p>The following simple example loads a video chunk by chunk as fast as possible, playing it as soon as it can. This example was written by Nick Desaulniers and can be <a href="https://nickdesaulniers.github.io/netfix/demo/bufferAll.html">viewed live here</a> (you can also <a href="https://github.com/nickdesaulniers/netfix/blob/gh-pages/demo/bufferAll.html">download the source</a> for further investigation.)</p>

<pre class="brush: js">
var video = document.querySelector('video');

var assetURL = 'frag_bunny.mp4';
// Need to be specific for Blink regarding codecs
// ./mp4info frag_bunny.mp4 | grep Codec
var mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';

if ('MediaSource' in window &amp;&amp; MediaSource.isTypeSupported(mimeCodec)) {
  var mediaSource = new MediaSource;
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener('sourceopen', sourceOpen);
} else {
  console.error('Unsupported MIME type or codec: ', mimeCodec);
}

function sourceOpen (_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener('updateend', function (_) {
      mediaSource.endOfStream();
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
};

function fetchAB (url, cb) {
  console.log(url);
  var xhr = new XMLHttpRequest;
  xhr.open('get', url);
  xhr.responseType = 'arraybuffer';
  xhr.onload = function () {
    cb(xhr.response);
  };
  xhr.send();
};</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('Media Source Extensions', '#sourcebuffer', 'SourceBuffer')}}</td>
   <td>{{Spec2('Media Source Extensions')}}</td>
   <td>Initial definition.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<div>{{CompatibilityTable}}</div>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>23</td>
   <td>{{CompatGeckoDesktop("25.0")}}<sup>[1]</sup><br />
    {{CompatGeckoDesktop("42.0")}}</td>
   <td>11<sup>[2]</sup></td>
   <td>15</td>
   <td>8</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS (Gecko)</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>4.4.4</td>
   <td>
    <p>{{CompatNo}}</p>
   </td>
   <td>{{CompatNo}}</td>
   <td>11</td>
   <td>30</td>
   <td>{{CompatNo}}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] Available after switching the <code>about:config</code> preference <code>media.mediasource.enabled</code> to <code>true</code>. In addition, support was limited to a whitelist of sites, for example YouTube, Netflix, and other popular streaming sites. This was removed in 42+.</p>

<p>[2] Only works on Windows 8+.</p>

<h2 id="See_also">See also</h2>

<ul>
 <li>{{domxref("MediaSource")}}</li>
 <li>{{domxref("SourceBufferList")}}</li>
</ul>