WHATWG Streams API spec provides an API for representing and handling a stream of data in JavaScript. This W3C spec is intended to extend the WHATWG spec to meet requirements specific to the browser environment.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the W3C Web Applications (WebApps) as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All comments are welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 14 October 2005 W3C Process Document.

Table of Contents

1. Introduction

This section is non-normative.

Web applications should have the ability to acquire, manipulate, and pass data in a wide variety of forms, including as a sequence of data made available over time. The WHATWG Streams API specification defines the basic representation for streams of data, and programmatic ways to read and write streams of data and errors raised on those operations. This W3C spec had been defining a Streams API, but has been merged into the effort at WHATWG. Feedback made for the W3C spec has been incorporated into the WHATWG Streams API specification. Currently, the goal of this spec is for discussing and defining extensions to meet requirements specific to the browser environment.

The WritableStream interface defines a general protocol for data consuming APIs to communicate with data producing code. In these cases, the data consuming API, such as a decoder, provides a WritableStream for other applications to write to, enabling the decoder to begin decoding data as it becomes available.

The ReadableStream interface defines a general protocol for data producing APIs to communicate with data consuming code. This interface represents the potential for an infinite amount of data which are obtained over time and read once.

The WritableByteStream interface is extended version of WritableStream which has functionality for high performance binary data handling.

The ReadableByteStream interface is extended version of ReadableStream which has functionality for high performance binary data handling. As well as Blob, it might be worth providing a way to get a URL from which we can load data stored in a ReadableByteStream.

The example below demonstrates how to obtain a ReadableByteStream from XMLHttpRequest to begin playing a large video in readystate LOADING. The example takes the ReadableByteStream from a producer, XMLHttpRequest, and gives it to a consumer, the video tag.

Example 1
function handler() {
  if (this.readyState == this.LOADING) {
    var rbs = this.response;
    var rbsURL = URL.createObjectURL(rbs);
    document.getElementById("placeToPlayMyVideo").src = rbsURL;

var client = new XMLHttpRequest();
client.onreadystatechange = handler;
client.open("GET", "/myvideo");
client.responseType = "stream";

2. Extension to WritableByteStream

It might be worth adding an option to pass a pair of a DOMString and an encoding identifier to the write() method. This parameter could be provided as an attribute of the stream instead of the argument of the write() method as it's not likely to be changed frequently.

3. Extension to ReadableByteStream

It was discussed that the ReadableByteStream should provide a method to read data in various form such as Blob, ArrayBuffer, etc. However, the stream may receive data from the underlying sink without preceding read() call. It would be inefficient to create a data holder of the type specified on read() call. Type specification method should be done on the API instead of being included in the Streams API. The same argument applies to the functionality to specify the encoding using which the read data will be converted into a DOMString.

4. Stream Consumers and Producers

Byte streams can be both produced and consumed by various APIs. APIs which create streams are identified as producers, and ones which read and act on a byte stream are known as consumers. This section identifies some of the notable APIs where Streams may be produced and consumed.

The list of producers and consumers below is not an exhaustive list. It is placed here as informative for the time being.

4.1 Stream Consumers

This section outlines APIs which can consume a byte stream

4.2 Stream Producers

This section outlines APIs which can produce a byte stream

5. Security Considerations

A ReadableByteStream should have the same security considerations as a Blob. This is outlined in 6.8. Security Considerations of the File API specification. [FILE-API] Because a ReadableByteStream uses a Blob URI, cross origin requests on a ReadableByteStream will not be supported.

A. Acknowledgements

Thanks to Eliot Graff for editorial assistance. Special thanks to the W3C. The editor would like to thank Adrian Bateman, Anne van Kesteren, Austin William Wright, Aymeric Vitte, Domenic Denicola, Elliott Sprehn, Francois-Xavier Kowalski, Harris Syed, Isaac Schlueter, Jonas Sicking, Kenneth Russell, Kinuko Yasuda, Lindsay Verola, Michael Davidson, Rob Manson, Taiju Tsuiki, Yusuke Suzuki, Yutaka Hirano, for their contributions to this specification.

B. References

B.1 Normative references

Arun Ranganathan; Jonas Sicking. File API. 12 September 2013. W3C Last Call Working Draft. URL: http://www.w3.org/TR/FileAPI/

This is an older spec snapshot. Implementors and reviewers should instead read the latest specification, which is up to date with the latest changes and bug fixes.