- From: CVS User dburnett <cvsmail@w3.org>
- Date: Sun, 17 Aug 2014 13:18:17 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2011/webrtc/editor/sources
In directory roscoe:/tmp/cvs-serv30317/sources
Modified Files:
getusermedia.html getusermedia.js
Log Message:
Added 20140817 archived version.
--- /sources/public/2011/webrtc/editor/sources/getusermedia.html 2014/07/04 11:39:01 1.6
+++ /sources/public/2011/webrtc/editor/sources/getusermedia.html 2014/08/17 13:18:17 1.7
@@ -1,5117 +1,4950 @@
+<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<!--
To publish this document, see instructions in README
-->
+<html lang="en-us" xml:lang="en-us" xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:ns="http://www.w3.org/1999/xhtml">
+ <head>
+ <link href="getusermedia.css" rel="stylesheet" type="text/css" />
+
+ <title>Media Capture and Streams</title>
+
+ <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
+
+ <script class="remove"
+ src="http://www.w3.org/Tools/respec/respec-w3c-common"
+ type="text/javascript"> // <!-- keep this comment --> // </script>
+
+ <script class="remove" src="getusermedia.js" type="text/javascript"> //
+ <!-- keep this comment --> // </script>
+ </head>
+
+ <body>
+ <section id="abstract">
+ <p>This document defines a set of JavaScript APIs that allow local
+ media, including audio and video, to be requested from a platform.</p>
+ </section>
-<html lang="en-us" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-us">
-<head>
- <link href="getusermedia.css" rel="stylesheet" type="text/css" />
+ <section id="sotd">
+ <p>This document is not complete. It is subject to major changes and,
+ while early experimentations are encouraged, it is therefore not
+ intended for implementation. The API is based on preliminary work done
+ in the WHATWG.</p>
+ </section>
- <title>Media Capture and Streams</title>
- <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
- <script class="remove" src="http://www.w3.org/Tools/respec/respec-w3c-common"
- type="text/javascript">
-//<![CDATA[
- <!-- keep this comment -->
- //]]>
- </script>
- <script class="remove" src="getusermedia.js" type="text/javascript">
-//<![CDATA[
- <!-- keep this comment -->
- //]]>
- </script>
-</head>
+ <section class="informative" id="intro">
+ <h2>Introduction</h2>
-<body>
- <section id="abstract">
- <p>This document defines a set of JavaScript APIs that allow local media,
- including audio and video, to be requested from a platform.</p>
- </section>
+ <p>Access to multimedia streams (video, audio, or both) from local
+ devices (video cameras, microphones, Web cams) can have a number of
+ uses, such as real-time communication, recording, and surveillance.</p>
+
+ <p>This document defines the APIs used to get access to local devices
+ that can generate multimedia stream data. This document also defines the
+ MediaStream API by which JavaScript is able to manipulate the stream
+ data or otherwise process it.</p>
+ </section>
+ <section id="conformance">
+ <p>This specification defines conformance criteria that apply to a
+ single product: the <dfn>user agent</dfn> that implements the interfaces
+ that it contains.</p>
+
+ <p>Conformance requirements phrased as algorithms or specific steps may
+ be implemented in any manner, so long as the end result is equivalent.
+ (In particular, the algorithms defined in this specification are
+ intended to be easy to follow, and not intended to be performant.)</p>
+
+ <p>Implementations that use ECMAScript to implement the APIs defined in
+ this specification must implement them in a manner consistent with the
+ ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as
+ this specification uses that specification and terminology.</p>
+ </section>
- <section id="sotd">
- <p>This document is not complete. It is subject to major changes and, while
- early experimentations are encouraged, it is therefore not intended for
- implementation. The API is based on preliminary work done in the
- WHATWG.</p>
- </section>
+ <section>
+ <h2>Terminology</h2>
+ <dl>
+ <dt>
+ <i>HTML Terms:</i>
+ </dt>
- <section class="informative" id="intro">
- <h2>Introduction</h2>
+ <dd>
+ <p>The <code>
+ <a
+ href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">EventHandler</a>
+ </code> interface represents a callback used for event handlers as
+ defined in [[!HTML5]].</p>
+
+ <p>The concepts <dfn>
+ <a
+ href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">queue
+ a task</a>
+ </dfn> and <dfn>
+ <a
+ href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">fires
+ a simple event</a>
+ </dfn> are defined in [[!HTML5]].</p>
+
+ <p>The terms <dfn>
+ <a
+ href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">event
+ handlers</a>
+ </dfn> and <dfn>
+ <a
+ href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
+ event handler event types</a>
+ </dfn> are defined in [[!HTML5]].</p>
+ </dd>
+ <dt>
+ <dfn>source</dfn>
+ </dt>
- <p>Access to multimedia streams (video, audio, or both) from local devices
- (video cameras, microphones, Web cams) can have a number of uses, such as
- real-time communication, recording, and surveillance.</p>
+ <dd>
+ <p>A source is the "thing" providing the source of a media stream
+ track. The source is the broadcaster of the media itself. A source
+ can be a physical webcam, microphone, local video or audio file from
+ the user's hard drive, network resource, or static image.</p>
+
+ <p>Some sources have an identifier which <em class="rfc2119"
+ title="must">must</em> be unique to the application (un-guessable by
+ another application) and persistent between application sessions
+ (e.g., the identifier for a given source device/application must
+ stay the same, but not be guessable by another application). Sources
+ that must have an identifier are camera and microphone sources;
+ local file sources are not required to have an identifier. Source
+ identifiers let the application save, identify the availability of,
+ and directly request specific sources.</p>
+
+ <p>Other than the identifier, other bits of source identity are
+ <strong>never</strong> directly available to the application until
+ the user agent connects a source to a track. Once a source has been
+ "released" to the application (either via a permissions UI,
+ pre-configured allow-list, or some other release mechanism) the
+ application will be able discover additional source-specific
+ capabilities.</p>
+
+ <p>Sources <strong>do not</strong> have constraints -- tracks have
+ constraints. When a source is connected to a track, it must,
+ possibly in combination with UA processing (e.g., downsampling),
+ conform to the constraints present on that track (or set of
+ tracks).</p>
+
+ <p>Sources will be released (un-attached) from a track when the
+ track is ended for any reason.</p>
+
+ <p>On the <code>
+ <a>MediaStreamTrack</a>
+ </code> object, sources are represented by a <code>
+ <a>sourceType</a>
+ </code> attribute. The behavior of APIs associated with the
+ source's capabilities and settings change depending on the source
+ type.</p>
+
+ <p>Sources have <code>
+ <a>capabilities</a>
+ </code> and <code>
+ <a>settings</a>
+ </code>. The capabilities and settings are "owned" by the source
+ and are common to any (multiple) tracks that happen to be using the
+ same source (e.g., if two different track objects bound to the same
+ source ask for the same capability or setting information, they will
+ get back the same answer).</p>
+ </dd>
+ <dt> <a>Setting</a> (Source Setting) </dt>
- <p>This document defines the APIs used to get access to local devices that
- can generate multimedia stream data. This document also defines the
- MediaStream API by which JavaScript is able to manipulate the stream data
- or otherwise process it.</p>
- </section>
+ <dd>
+ <p>A setting refers to the immediate, current value of the source's
+ (optionally constrained) capabilities. Settings are always
+ read-only.</p>
+
+ <p>A source's settings can change dynamically over time due to
+ environmental conditions, sink configurations, or constraint
+ changes. A source's settings must always conform to the current set
+ of mandatory constraints that all of the tracks it is bound to have
+ defined, and should do its best to conform to the set of optional
+ constraints specified.</p>
+
+ <p>Although settings are a property of the source, they are only
+ exposed to the application through the tracks attached to the
+ source. The <a>ConstrainablePattern</a> interface provides this
+ exposure.</p>
+
+ <p>A conforming user-agent <em class="rfc2119"
+ title="must">must</em> support all the setting names defined in this
+ spec.</p>
+ </dd>
+ <dt>
+ <a>Capabilities</a>
+ </dt>
- <section id="conformance">
- <p>This specification defines conformance criteria that apply to a single
- product: the <dfn>user agent</dfn> that implements the interfaces that it
- contains.</p>
+ <dd>
+ <p>Source capabilities are the intrinsic "features" of a source
+ object. For each source setting, there is a corresponding capability
+ that describes whether it is supported by the source and if so, what
+ the range of supported values are. As with settings, capabilities
+ are exposed to the application via the <a>ConstrainablePattern</a>
+ interface.</p>
+
+ <p>The values of the supported capabilities must be normalized to
+ the ranges and enumerated types defined in this specification.</p>
+
+ <p>A <a>getCapabilities()</a> call on a track returns the same
+ underlying per-source capabilities for all tracks connected to the
+ source.</p>
+
+ <p>Source capabilities are effectively constant. Applications should
+ be able to depend on a specific source having the same capabilities
+ for any session.</p>
+ </dd>
+ <dt>
+ <a>Constraints</a>
+ </dt>
- <p>Conformance requirements phrased as algorithms or specific steps may be
- implemented in any manner, so long as the end result is equivalent. (In
- particular, the algorithms defined in this specification are intended to be
- easy to follow, and not intended to be performant.)</p>
+ <dd>
+ <p>Constraints are an optional track feature for restricting the
+ range of allowed variability on a source. Without provided track
+ constraints, implementations are free to select a source's settings
+ from the full ranges of its supported capabilities, and to adjust
+ those settings at any time for any reason.</p>
+
+ <p>Constraints are exposed on tracks via the
+ <a>ConstrainablePattern</a> interface, which includes an API for
+ dynamically changing constraints. Note that <a>getUserMedia()</a>
+ also permits an initial set of constraints to be applied when the
+ track is first obtained.</p>
+
+ <p>It is possible for two tracks that share a unique source to apply
+ contradictory constraints. The <a>ConstrainablePattern</a> interface
+ supports the calling of an error handler when the conflicting
+ constraint is requested. After successful application of constraints
+ on a track (and its associated source), if at any later time the
+ track becomes <a>overconstrained</a>, the user agent MUST change the
+ track to the <a>muted</a> state.</p>
+
+ <p>A correspondingly-named constraint exists for each corresponding
+ source setting name and capability name. In general, user agents
+ will have more flexibility to optimize the media streaming
+ experience the fewer constraints are applied, so application authors
+ are strongly encouraged to use mandatory constraints sparingly.</p>
+ </dd>
+ <dt>
+ <code>RTCPeerConnection</code>
+ </dt>
+
+ <dd><dfn>
+ <code>RTCPeerConnection</code>
+ </dfn> is defined in [[!WEBRTC10]].</dd>
+ </dl>
+ </section>
- <p>Implementations that use ECMAScript to implement the APIs defined in
- this specification must implement them in a manner consistent with the
- ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as
- this specification uses that specification and terminology.</p>
- </section>
+ <section id="stream-api">
+ <h2>MediaStream API</h2>
+ <section>
+ <h2>Introduction</h2>
- <section>
- <h2>Terminology</h2>
+ <p>The two main components in the MediaStream API are the <code>
+ <a>MediaStreamTrack</a>
+ </code> and the <code>
+ <a>MediaStream</a>
+ </code> interfaces. The <code>
+ <a>MediaStreamTrack</a>
+ </code> object represents media originating from a single media
+ source in the user agent, e.g. video from a web camera. A <code>
+ <a>MediaStream</a>
+ </code> is used group several <code>
+ <a>MediaStreamTrack</a>
+ </code> objects into one unit that can be rendered in a media
+ element or recorded.</p>
+
+ <p>Each <code>
+ <a>MediaStream</a>
+ </code> can contain zero or more <code>
+ <a>MediaStreamTrack</a>
+ </code> objects. All tracks in a <code>
+ <a>MediaStream</a>
+ </code> are intended to be synchronized when rendered. Different
+ <code>
+ <a>MediaStream</a>
+ </code> objects do not need to be synchronized.</p>
+
+ <p class="note">While the intent is to synchronize tracks, it could be
+ better in some circumstances to permit tracks to lose
+ synchronization.In particular, when tracks are remotely sourced and
+ real-time [[!WEBRTC10]], it can be better to allow loss of
+ synchronization than to accumulate delays or risk glitches and other
+ artifacts. Implementations are expected to understand the implications
+ of choices regarding synchronization of playback and the effect that
+ these have on user perception.</p>
+
+ <p>A <code>
+ <a>MediaStreamTrack</a>
+ </code> represents content comprising one or more channels, where
+ the channels have a defined well known relationship to each other
+ (such as a stereo or 5.1 audio signal). A channel is the smallest unit
+ considered in this API specification.</p>
+
+ <p>
+ <img alt="A MediaStream" src="images/media-stream.png" width="418" />
+ </p>
+
+ <p>A <code>
+ <a>MediaStream</a>
+ </code> object has an input and an output that represent the
+ combined input and output of all the object's tracks. The output of
+ the <code>
+ <a>MediaStream</a>
+ </code> controls how the object is rendered, e.g., what is saved if
+ the object is recorded to a file or what is displayed if the object is
+ used in a <code>video</code> element.</p>
+
+ <p>A new <code>
+ <a>MediaStream</a>
+ </code> object can be created from accessible media sources (that
+ does not require any additional permissions) using the <code>
+ <a href="#dom-mediastream">MediaStream()</a>
+ </code> constructor. The constructor argument can either be an
+ existing <code>
+ <a>MediaStream</a>
+ </code> object, in which case all the tracks of the given stream are
+ added to the new <code>
+ <a>MediaStream</a>
+ </code> object, or an array of <code>
+ <a>MediaStreamTrack</a>
+ </code> objects. The latter form makes it possible to compose a
+ stream from different source streams.</p>
+
+ <p>Both <code>
+ <a>MediaStream</a>
+ </code> and <code>
+ <a>MediaStreamTrack</a>
+ </code> objects can be cloned. This allows for greater control since
+ the separate instances can be manipulated and <a
+ title="consumer">consumed</a> individually. A cloned <code>
+ <a>MediaStream</a>
+ </code> contains clones of all member tracks from the original
+ stream.</p>
+
+ <p>When a <code>
+ <a>MediaStream</a>
+ </code> object is being generated from a local file (as opposed to a
+ live audio/video source), the user agent SHOULD stream the data from
+ the file in real time, not all at once. The <code>MediaStream</code>
+ object is also used in contexts outside <code>getUserMedia</code>,
+ such as [[!WEBRTC10]]. In both cases, ensuring a realtime stream
+ reduces the ease with which pages can distinguish live video from
+ pre-recorded video, which can help protect the user's privacy.</p>
+ </section>
[8983 lines skipped]
--- /sources/public/2011/webrtc/editor/sources/getusermedia.js 2014/07/04 11:39:01 1.6
+++ /sources/public/2011/webrtc/editor/sources/getusermedia.js 2014/08/17 13:18:17 1.7
@@ -19,7 +19,7 @@
// copyrightStart: "2005",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD
- prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20140619/getusermedia.html",
+ prevED: "http://dev.w3.org/2011/webrtc/editor/archives/20140704/getusermedia.html",
// if there a publicly available Editor's Draft, this is the link
edDraftURI: "http://dev.w3.org/2011/webrtc/editor/getusermedia.html",
Received on Sunday, 17 August 2014 13:18:19 UTC