Overview.htm
author Art Barstow <art.barstow@gmail.com>
Tue, 21 Oct 2014 10:27:36 -0400
changeset 167 279185b12a8b
parent 166 e5b689ded0d6
child 169 891635210233
permissions -rw-r--r--
WD snapshot for 2014 Oct 23
<!DOCTYPE html>

<html>

<head>
	<title>Streams API</title>
	<meta content="text/html;charset=utf-8" http-equiv="Content-Type">

	<!-- <script class=remove src="http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js"></script> -->
	<script class="remove" src="https://www.w3.org/Tools/respec/respec-w3c-common"></script>
	<!-- <script class="remove" src="respec-w3c-common.js"></script> -->

	<script class="remove">
var respecConfig = {
	// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
	specStatus:           "ED",

	// the specification's short name, as in http://www.w3.org/TR/short-name/
	shortName:            "streams-api",

	// if your specification has a subtitle that goes below the main
	// formal title, define it here
	// subtitle   :  "an excellent document",

	// if you wish the publication date to be other than today, set this
	publishDate:  "2014-10-01",

	// if the specification's copyright date is a range of years, specify
	// the start date here:
	// copyrightStart: "2005"

	// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
	// and its maturity status
	// previousPublishDate:  "yyyy-mm-dd",
	// previousMaturity:  "WD",

	// if there a publicly available Editor's Draft, this is the link
	edDraftURI:           "http://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm",

	// if this is a LCWD, uncomment and set the end of its review period
	// lcEnd: "2009-08-05",

	// if you want to have extra CSS, append them to this list
	// it is recommended that the respec.css stylesheet be kept
	//extraCSS:             ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css",
	//	"http://www.w3.org/StyleSheets/TR/W3C-ED.css",
	//	],

	// editors, add as many as you like
	// only "name" is required

	localBiblio: {
		"EncodingDetermination": {
			title: "Encoding",
			href: "http://encoding.spec.whatwg.org/",
			authors: ["Anne van Kesteren", "Joshua Bell"],
			publisher: "WHATWG"
		}
	},

	editors:  [
		{ name: "Feras Moussa", url: "mailto:feras.moussa@hotmail.com",
			company: "Invited Expert",  },
		{ name: "Takeshi Yoshino", url: "mailto:tyoshino@google.com",
			company: "Google, Inc.",  },
	],

	// authors, add as many as you like.
	// This is optional, uncomment if you have authors as well as editors.
	// only "name" is required. Same format as editors.

	//authors:  [
	//    { name: "Your Name", url: "http://example.org/",
	//      company: "Your Company", companyURL: "http://example.com/" },
	//],

	// name of the WG
	wg:           "W3C Web Applications (WebApps)",

	// URI of the public WG page
	wgURI:        "http://www.w3.org/2008/webapps/",

	// name (with the @w3c.org) of the public mailing to which comments are due
	wgPublicList: "public-webapps",

	// URI of the patent status for this WG, for Rec-track documents
	// !!!! IMPORTANT !!!!
	// This is important for Rec-track documents, do not copy a patent URI from a random
	// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
	// Team Contact.
	wgPatentURI:  "",
};
</script>

	<!-- Styles to mimic File API spec -->
	<!-- <style type="text/css"> -->
	<!-- 	table.error { border-collapse:collapse; border-style:hidden hidden none hidden } -->
	<!-- 	table.error thead { border-bottom:solid } -->
	<!-- 	table.error tbody th:first-child { border-left:solid } -->
	<!-- 	table.error td, table th { border-left:solid; border-right:solid; border-bottom:solid thin; vertical-align:top; padding:0.2em } -->
	<!-- </style> -->

</head>
<body>

	<section id="sotd">
		<p>
                  <ul>
                    <li>To check recent changes and rationale for them, please visit <a href="https://dvcs.w3.org/hg/streams-api/">Mercurial history</a>.
                    <li>Check open bugs at Bugzilla using <a href="https://www.w3.org/Bugs/Public/buglist.cgi?component=Streams%20API">this link</a>.
                    <li>If you wish to submit a bug, please use <a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?product=WebAppsWG&component=Streams%20API">this link</a>.
                  </ul>
		</p>
	</section>

	<section id="abstract">
		<p>
			<a href="https://github.com/whatwg/streams">WHATWG Streams API</a> provides an API for representing and handling a stream of data in web applications.
			This specification is intended to extend the spec to meet requirements specific to the browser environment.
		</p>
	</section>

	<section id="introduction" class="section informative">
		<h2>Introduction</h2>

		<p>
			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.
			This <a href="https://github.com/whatwg/streams">WHATWG Streams API</a> 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.
		</p>

		<p>
			The WritableStream interface defines a general protocol for <a href="#consumers">data consuming APIs</a> 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.
		</p>

		<p>
			The ReadableStream interface defines a general protocol for <a href="#producers">data producing APIs</a> 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.
		</p>

                <p>
                  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.
                </p>

		<p>
			The example below demonstrates how to obtain a ReadableByteStream from XMLHttpRequest to begin playing a large video in <code>readystate</code> LOADING.
			The example takes the ReadableByteStream from a <a href="#producers">producer</a>, XMLHttpRequest, and gives it to a <a href="#consumers">consumer</a>, the video tag.
		</p>

		<pre class="example">
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";
client.send();</pre>
	</section>

	<section class="section" id="writableStream">
          <h2>Extension to WritableByteStream</h2>

          <p>
            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.
          </p>
	</section>

	<section class="section" id="readableStream">
	  <h2>Extension to ReadableByteStream</h2>

          <p>
            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.
          </p>
	</section>

	<section class="section" id="producers-consumers">
		<h2>Stream Consumers and Producers</h2>
		<p>
			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.
			<section class="note">The list of producers and consumers below is not an exhaustive list. It is placed here as informative for the time being.</section>
		</p>
		<section class="section" id="consumers">
			<h2>Stream Consumers</h2>
			<p>This section outlines APIs which can consume a byte stream</p>
			<ul>
				<li>XMLHttpRequest</li>
				<li>Web Audio</li>
				<li>Media Source Extensions</li>
				<li>Web Cryptography API</li>
				<li>TextEncoder</li>
				<li>TextDecoder</li>
				<li>WebSockets</li>
				<li>RTCPeerConnection</li>
				<li>FileWriter</li>
			</ul>
		</section>

		<section class="section" id="producers">
			<h2>Stream Producers</h2>
			<p>This section outlines APIs which can produce a byte stream</p>
			<ul>
				<li>XMLHttpRequest</li>
				<li>FileReader</li>
				<li>Media Capture</li>
				<li>MediaStream Recording API</li>
				<li>Indexed Database</li>
				<li>Web Cryptography API</li>
				<li>TextEncoder</li>
				<li>TextDecoder</li>
				<li>WebSockets</li>
				<li>EventSource</li>
				<li>RTCPeerConnection</li>
			</ul>
		</section>
	</section>

	<section class="section" id="security">
		<h2>Security Considerations</h2>
		<p>
			A ReadableByteStream should have the same security considerations as a <code>Blob</code>.
			This is outlined in <a href="http://dev.w3.org/2006/webapi/FileAPI/#security-discussion">6.8. Security Considerations</a>
			of the File API specification. [[!FILE-API]]
			Because a ReadableByteStream uses a <code>Blob URI</code>, cross origin requests on a ReadableByteStream will not be supported.
		</p>
	</section>

	<section class=appendix>
		<h2>Acknowledgements</h2>
		<p>
			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.
		</p>
	</section>

</body>
</html>