- From: Ilkka Oksanen via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 22 Mar 2010 16:33:08 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/camera
In directory hutz:/tmp/cvs-serv14990
Modified Files:
Overview.html
Log Message:
Whitespace changes only.
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/camera/Overview.html,v
retrieving revision 1.49
retrieving revision 1.50
diff -u -d -r1.49 -r1.50
--- Overview.html 18 Mar 2010 09:43:02 -0000 1.49
+++ Overview.html 22 Mar 2010 16:33:06 -0000 1.50
@@ -21,22 +21,32 @@
<script src='../common/config.js' class='remove'></script>
</head>
<body>
- <section id='abstract'>
- This specification defines an Application Programming Interface (<acronym title="Application Programming Interface">API</acronym>) that provides access to the audio, image and video capture capabilities of the device.
+
+ <section id='abstract'>
+ This specification defines an Application Programming Interface
+ (<acronym title="Application Programming Interface">API</acronym>)
+ that provides access to the audio, image and video capture
+ capabilities of the device.
</section>
-<section>
-<h2>Introduction</h2>
+ <section>
+ <h2>Introduction</h2>
-<p>The Capture API defines a high-level interface for accessing the microphone and camera of a hosting device.</p>
+ <p>The Capture API defines a high-level interface for accessing the
+ microphone and camera of a hosting device.</p>
+
+ <section id="examples">
+ <h2>Usage Examples</h2>
+
+ <p>The following code extracts illustrate how to work with a
+ camera service in the hosting device:</p>
+
+ <div>
+ <p>Launching a device camera application and retrieving the
+ pictures taken. </p>
+
+ <pre class="example sh_javascript_dom">
-<section id="examples">
-<h2>Usage Examples</h2>
-<p>The following code extracts illustrate how to work with a camera service in the hosting device:
-</p>
-<div>
-<p>Launching a device camera application and retrieving the pictures taken. </p>
-<pre class="example sh_javascript_dom">
function success(data) {
var container = document.createElement("div");
document.body.appendChild(container);
@@ -53,259 +63,424 @@
}
navigator.device.captureImage(success, error, { limit: 1 });
-</pre>
-</div>
-<div>
-<p>Example of retrieving image sizes and formats supported by hosting device camera.</p>
-<pre class="example sh_javascript_dom">var summary,
- formats = navigator.device.supportedImageFormats;
+
+ </pre>
+ </div>
+ <div>
+
+ <p>Example of retrieving image sizes and formats supported by hosting
+ device camera.</p>
+
+ <pre class="example sh_javascript_dom">var summary,
+
+formats = navigator.device.supportedImageFormats;
for (var key in formats) {
summary += key + ": " + formats[key] + "\n";
}
-alert(summary);</pre>
-</div>
-</section>
-</section>
+alert(summary);
-<section id="security">
+ </pre>
+ </div>
+ </section>
+ </section>
-<h2>Security and Privacy Considerations</h2>
+ <section id="security">
+ <h2>Security and Privacy Considerations</h2>
-<p class='note'>
- <strong>This section is under development.</strong>
-</p>
+ <p class='note'>
+ <strong>This section is under development.</strong>
+ </p>
-<p>
-The API defined in this specification launches the capture application
-which allows the user to take pictures, record voice or record video
-and provides a handle to the content. This information can
-potentially compromise user privacy and a conforming implementation
-of this specification MUST provide a mechanism that protects the
-user's privacy and this mechanism should ensure that such operations
-MUST be authenticated.
-</p>
+ <p>The API defined in this specification launches the capture
+ application which allows the user to take pictures, record voice or
+ record video and provides a handle to the content. This information
+ can potentially compromise user privacy and a conforming
+ implementation of this specification MUST provide a mechanism that
+ protects the user's privacy and this mechanism should ensure that such
+ operations MUST be authenticated.</p>
-<h3>Privacy considerations for implementers of Capture API</h3>
+ <h3>Privacy considerations for implementers of Capture API</h3>
-<p>
-A conforming implementation of this specification MUST provide a
-mechanism that protects the user's privacy and this mechanism SHOULD
-ensure that privacy information is not revealed without user's
-informed consent.
-</p>
+ <p>A conforming implementation of this specification MUST provide a
+ mechanism that protects the user's privacy and this mechanism SHOULD
+ ensure that privacy information is not revealed without user's
+ informed consent.</p>
-</section>
+ </section>
-<section id="api">
-<h2>API Description</h2>
-<section id="capture">
-<h3><a>Capture</a> interface</h3>
-<p>The <code>Capture</code> interface exposes an interface to the camera and microphone of the hosting device.</p>
+ <section id="api">
+ <h2>API Description</h2>
-<p class="issue">Where does it hang off of? Example given above assumes navigator.device — in which case we need to define a <code>NavigatorDevice</code> interface somewhere.</p>
-<p>Objects implementing the <code>NavigatorDevice</code> interface (e.g. the <code>window.navigator.device</code> object in Web browsers [[NAVIGATOR]]) provide access to the <code>Capture</code> interface through the <code>Capture</code> interface. An instance of <code>Capture</code> would be then obtained by using binding-specific casting methods on an instance of <code>NavigatorDevice</code>.</p>
+ <section id="capture">
+ <h3><a>Capture</a> interface</h3>
-<dl title="[Supplemental, NoInterfaceObject] interface Capture" class="idl"><dt>readonly attribute sequence<FormatData> supportedImageFormats
-</dt><dd>A sequence of FormatData objects which contains image sizes and formats supported by the hosting device camera.
-</dd><dt>readonly attribute sequence<FormatData> supportedVideoFormats </dt><dd>A sequence of FormatData objects which contains video resolutions and formats supported by the hosting device camera.
-</dd><dt>readonly attribute sequence<FormatData> supportedAudioFormats </dt><dd>A sequence of FormatData objects which contains audio formats supported by the hosting device microphone.
-</dd><dt>PendingOperation captureImage () </dt><dd>
-<p>Launch device native camera application for taking image(s).</p>
-<p>This method takes two or three arguments. When called, it immediately returns a
-<a href="#pendingoperation-interface"><code>PendingOperation</code></a> object and then asynchronously start a
-<em>capture image</em> process defined as follows:</p>
-<p></p>
-<ol>
- <li>Start native camera application. Allow end user to take picture(s).</li>
- <li>If successful, invoke the associated <code>successCB</code> with a <a href="#mediaarray-typedef">
- <code>MediaArray</code></a> argument. If the attempt fails, and the method was invoked with a non-null
- <code>errorCallback</code> argument, this method must invoke the <code>errorCallback</code> with a
- <a href="#captureerror-interface"><code>CaptureError</code></a> object as an argument.
- </li>
- <li>If a <code>CaptureImageOptions</code> parameter was present, and its <code>limit</code> attribute was defined,
- <code>successCB</code> MUST be invoked after the user has captured a number of images defined in <code>limit</code>.
- If user exited the native camera application prematurely, <code>errorCB</code> must be invoked.
- </li>
-</ol>
-<p></p>
+ <p>The <code>Capture</code> interface exposes an interface to the
+ camera and microphone of the hosting device.</p>
-<dl class="parameters">
- <dt>CaptureCB successCB </dt>
- <dd>Function to call when the asynchronous operation completes </dd>
- <dt>optional CaptureErrorCB? errorCB </dt>
- <dd>Function to call when the asynchronous operation fails. This parameter is OPTIONAL.</dd>
- <dt>optional CaptureImageOptions options </dt>
- <dd>Image capture options. This parameter is OPTIONAL.</dd>
-</dl>
+ <p class="issue">Where does it hang off of? Example given above
+ assumes navigator.device — in which case we need to
+ define a <code>NavigatorDevice</code> interface somewhere.</p>
-</dd><dt>PendingOperation captureVideo () </dt><dd>
-<p>Launch device native camera application for recording video(s).</p>
-<p>This method takes three or four arguments. When called, it immediately returns a
-<a href="#pendingoperation-interface"><code>PendingOperation</code></a> object and then asynchronously start a
-<em>capture video</em> process defined as follows:</p>
-<p></p>
-<ol>
-<li>Start native video camera application. Allow end user to take video(s) and return.
-</li><li>If successful, invoke the associated <code>successCB</code> with a <a href="#mediaarray-typedef">
-<code>MediaArray</code></a> argument. If the attempt fails, and the method was invoked with a non-null
-<code>errorCallback</code> argument, this method must invoke the <code>errorCallback</code> with a
-<a href="#captureerror-interface"><code>CaptureError</code></a> object as an argument.
-</li>
-<li>If a <code>CaptureVideoOptions</code> parameter was present, and its <code>limit</code> attribute was defined,
- <code>successCB</code> MUST be invoked after the user has captured a number of video clips defined in <code>limit</code>.
- If user exited the native camera application prematurely, <code>errorCB</code> must be invoked.
-</li>
-<li>If a <code>CaptureVideoOptions</code> parameter was present, and its <code>duration</code> attribute was defined,
- <code>successCB</code> MUST be invoked after the video has been captured for the number of milliseconds defined in
- <code>duration</code>.
- If user exited the native camera application prematurely, <code>errorCB</code> must be invoked.
-</li>
-</ol>
-<p></p>
+ <p>Objects implementing the <code>NavigatorDevice</code>
+ interface (e.g. the <code>window.navigator.device</code> object
+ in Web browsers [[NAVIGATOR]]) provide access to the
+ <code>Capture</code> interface through the <code>Capture</code>
+ interface. An instance of <code>Capture</code> would be then
+ obtained by using binding-specific casting methods on an
+ instance of <code>NavigatorDevice</code>.</p>
-<dl class="parameters">
- <dt>CaptureCB successCB </dt>
- <dd>Function to call when the asynchronous operation completes </dd>
- <dt>optional CaptureErrorCB? errorCB</dt>
- <dd>Function to call when the asynchronous operation fails. This parameter is OPTIONAL.</dd>
- <dt>optional CaptureVideoOptions options </dt>
- <dd>Image capture options. This parameter is OPTIONAL.</dd>
-</dl>
+ <dl title="[Supplemental, NoInterfaceObject] interface Capture"
+ class="idl"><dt>readonly attribute sequence<FormatData>
+ supportedImageFormats</dt>
-</dd><dt>PendingOperation captureAudio () </dt><dd>
-<p>Launch device native audio recorder application for recording audio clip(s).</p>
-<p>This method takes two or three arguments. When called, it immediately returns a
-<a href="#pendingoperation-interface"><code>PendingOperation</code></a> object and then asynchronously start a
-<em>capture audio</em> process defined as follows:</p>
-<p></p>
-<ol>
-<li>Start native audio recorder application. Allow end user to record audio clip(s) and return.
-</li>
-<li>If successful, invoke the associated <code>successCB</code> with a <a href="#mediaarray-typedef">
-<code>MediaArray</code></a> argument. If the attempt fails, and the method was invoked with a non-null
-<code>errorCallback</code> argument, this method must invoke the <code>errorCallback</code> with a
-<a href="#captureerror-interface"><code>CaptureError</code></a> object as an argument.
-</li>
-<li>If a <code>CaptureAudioOptions</code> parameter was present, and its <code>limit</code> attribute was defined,
- <code>successCB</code> MUST be invoked after the user has captured a number of audio clips defined in <code>limit</code>.
- If user exited the native camera application prematurely, <code>errorCB</code> must be invoked.
-</li>
-</ol>
+ <dd>A sequence of FormatData objects which contains image sizes
+ and formats supported by the hosting device camera.</dd>
-<p></p>
-<dl class="parameters">
- <dt>CaptureCB successCB </dt>
- <dd>Function to call when the asynchronous operation completes </dd>
- <dt>optional CaptureErrorCB? errorCB </dt>
- <dd>Function to call when the asynchronous operation fails. This parameter is OPTIONAL.</dd>
- <dt>optional CaptureAudioOptions options </dt>
- <dd>Audio capture options. This parameter is OPTIONAL.</dd>
-</dl>
-</dd></dl>
-</section><section id="mediadata"><h3><a>MediaData</a> interface</h3>
-<p><code>MediaData</code> captures a single photo, video or sound captured by the device native capture application.
-</p>
-<dl title="[NoInterfaceObject] interface MediaData" class="idl"><dt>attribute DOMString uri
-</dt><dd>The uri attribute attribute specifies the path to the media file taken by native application as a Uniform Resource Identifier (URI) conforming to [[URI]].
-</dd><dt>attribute FormatData format </dt><dd>The format attribute represents the media <a href="#formatdata-interface"><code>FormatData</code></a> object.
-</dd></dl>
-</section><section id="formatdata"><h3><a>FormatData</a> interface</h3>
-<p><code>FormatData</code> captures format information of a media file captured by the device native capture application.
-</p>
-<dl title="[NoInterfaceObject] interface FormatData" class="idl"><dt>attribute DOMString type
-</dt><dd>The type attribute represents the MIME type of the captured image, video or sound. For example, a valid MIME type for JPEG images is image/jpeg. A valid MIME type for WAV sound file is audio/x-wav.
-</dd><dt>attribute unsigned long height </dt><dd>The height attribute represents height of the image or video in pixels. Not applicable for a sound clip.
-</dd><dt>attribute double duration </dt><dd>The duration attribute represents length of the video or sound clip in milliseconds. Not applicable for an image.
-</dd><dt>attribute unsigned long width </dt><dd>The width attribute represents width of the image or video in pixels. Not applicable for a sound clip.
-</dd></dl>
-</section><section id="capturecallbak"><h3><a>CaptureCB</a> interface</h3>
-<dl title="[Callback=FunctionOnly, NoInterfaceObject] interface CaptureCB" class="idl">
-<dt>void onSuccess () </dt><dd>
-<dl class="parameters"><dt>MediaArray capturedMedia </dt><dd>Sequence of MediaData successfully captured by the device</dd>
-</dd></dl>
-</dd></dl>
-</section>
+ <dt>readonly attribute sequence<FormatData>
+ supportedVideoFormats </dt>
+ <dd>A sequence of FormatData objects which contains video
+ resolutions and formats supported by the hosting device
+ camera.</dd>
-<section id="mediaarray"><h3><a>MediaArray</a> typedef</h3>
-<p>The <a>MediaArray</a> typedef represents a <code>sequence</code> of <a href="#mediadata-interface">
-<code>MediaData</code></a> objects. </p>
-<dl title="typedef sequence<MediaData> MediaArray" class="idl"></dl>
-</section><section id="errorcallback"><h3><a>CaptureErrorCB</a> interface</h3>
-<dl title="[Callback=FunctionOnly, NoInterfaceObject] interface CaptureErrorCB" class="idl">
-<dt>void onError () </dt><dd>
-<dl class="parameters"><dt>CaptureError error </dt><dd>The error object of an unsuccessful capture asynchronous operation. </dd></dl>
-</dd></dl>
-</section>
+ <dt>readonly attribute sequence<FormatData>
+ supportedAudioFormats</dt>
+ <dd>A sequence of FormatData objects which contains audio
+ formats supported by the hosting device microphone.</dd>
-<section id="captureerror"><h3><a>CaptureError</a> interface</h3>
-<p>The <a>CaptureError</a> interface encapsulates all errors in the Capture API. </p>
-<p class="note">More error codes to be defined here. </p>
-<dl title="[NoInterfaceObject] interface CaptureError" class="idl">
- <dt>const unsigned short CAPTURE_INTERNAL_ERR = 0 </dt>
- <dd>Camera or microphone failed to capture image or sound. </dd>
- <dt>readonly attribute unsigned short code </dt>
- <dd>An error code assigned by an implementation when an error has occurred in Capture API processing.</dd>
-</dl>
-</section>
+ <dt>PendingOperation captureImage () </dt>
+ <dd><p>Launch device native camera application for taking
+ image(s).</p>
-<section id="captureimageoptions"><h3><a>CaptureImageOptions</a> interface</h3>
-<p>The <a>CaptureImageOptions</a> interface encapsulates all image capture operation configuration options.</p>
-<p class="note">Additional attributes proposed: <code>width</code> and <code>height</code>.</p>
-<dl title="[NoInterfaceObject] interface CaptureImageOptions" class="idl">
- <dt>attribute unsigned long limit</dt>
- <dd>Upper limit of images user can take.</dd>
-</dl>
-</section>
+ <p>This method takes two or three arguments. When called, it
+ immediately returns a <a
+ href="#pendingoperation-interface"><code>PendingOperation</code></a>
+ object and then asynchronously start a <em>capture image</em>
+ process defined as follows:</p>
-<section id="capturevideooptions"><h3><a>CaptureVideoOptions</a> interface</h3>
-<dl title="[NoInterfaceObject] interface CaptureVideoOptions" class="idl">
- <dt>attribute unsigned long limit</dt>
- <dd>Upper limit of videos user can record.</dd>
- <dt>attribute double duration</dt>
- <dd>Maximum duration of a single video clip in milliseconds.</dd>
-</dl>
-</section>
+ <p></p>
-<section id="captureaudiooptions"><h3><a>CaptureAudioOptions</a> interface</h3>
-<p class="note">Additional attributes proposed: <code>duration</code>.</p>
-<dl title="[NoInterfaceObject] interface CaptureAudioOptions" class="idl">
- <dt>attribute unsigned long limit</dt>
- <dd>Upper limit of sound clips user can record.</dd>
-</dl>
-</section>
+ <ol>
-</section><section id="pendingoperation"><h3><a>PendingOperation</a> interface</h3>
-<p class="note">This may be a general interface for use throughout all APIs. Included here for now for completion.</p>
-<dl title="[NoInterfaceObject] interface PendingOperation" class="idl"><dt>void cancel ()
-</dt><dd>Cancel/clear the pending asynchronous operation. </dd></dl>
-</section>
-</section>
+ <li>Start native camera application. Allow end user to take
+ picture(s).</li>
-<section id="formaccess">
-<h2>Capture Input Selection</h2>
-<p>In addition to programmable API, content can be acquired from capture devices through a file-select control.</p>
+ <li>If successful, invoke the associated <code>successCB</code>
+ with a <a href="#mediaarray-typedef"> <code>MediaArray</code></a>
+ argument. If the attempt fails, and the method was invoked with a
+ non-null <code>errorCallback</code> argument, this method must
+ invoke the <code>errorCallback</code> with a <a
+ href="#captureerror-interface"><code>CaptureError</code></a> object
+ as an argument.</li>
-<section id="capture">
-<h2>Capture aware file-select control</h2>
+ <li>If a <code>CaptureImageOptions</code> parameter was present,
+ and its <code>limit</code> attribute was defined,
+ <code>successCB</code> MUST be invoked after the user has
+ captured a number of images defined in <code>limit</code>. If
+ user exited the native camera application prematurely,
+ <code>errorCB</code> must be invoked.</li> </ol>
+
+ <p></p>
-<p>This section is non-normative.</p>
+ <dl class="parameters">
+ <dt>CaptureCB successCB </dt>
+ <dd>Function to call when the asynchronous operation completes </dd>
-If input element in the File Upload state [[HTML5]] contains accept
-attribute with values <code>image/*</code>, <code>sound/*</code>,
-or <code>video/*</code>, the user agent can invoke a file picker
-that allows respectively the user to take a picture, record a sound file, or
-record a video in addition to selecting an existing
-file from the file system.
+ <dt>optional CaptureErrorCB? errorCB </dt>
+ <dd>Function to call when the asynchronous operation
+ fails. This parameter is OPTIONAL.</dd>
-In case the user chooses to capture video, audio, or image content, the user agent creates media files on the fly as specified in [[HTML5]].
+ <dt>optional CaptureImageOptions options </dt>
+ <dd>Image capture options. This parameter is OPTIONAL.</dd>
+ </dl>
+
+ </dd>
+
+ <dt>PendingOperation captureVideo ()</dt>
-<pre class="example sh_javascript_dom"><input id="cameraInput" type="file" accept="image/*"> </pre>
+ <dd>
-<p>In trusted environments the click event of file input element can be synthesised as follows:</p>
+ <p>Launch device native camera application for recording
+ video(s).</p>
-<pre class="example sh_javascript_dom"><input id="cameraInput" onchange="successCB();" type="file" accept="image/*">
+ <p>This method takes three or four arguments. When called, it
+ immediately returns a <a
+ href="#pendingoperation-interface"><code>PendingOperation</code></a>
+ object and then asynchronously start a <em>capture video</em> process
+ defined as follows:</p>
+
+ <p></p>
+
+ <ol>
+
+ <li>Start native video camera application. Allow end user to
+ take video(s) and return. </li><li>If successful, invoke the
+ associated <code>successCB</code> with a <a
+ href="#mediaarray-typedef"> <code>MediaArray</code></a> argument. If
+ the attempt fails, and the method was invoked with a non-null
+ <code>errorCallback</code> argument, this method must invoke the
+ <code>errorCallback</code> with a <a
+ href="#captureerror-interface"><code>CaptureError</code></a> object as
+ an argument.</li>
+
+ <li>If a <code>CaptureVideoOptions</code> parameter was present, and
+ its <code>limit</code> attribute was defined,
+ <code>successCB</code> MUST be invoked after the user has
+ captured a number of video clips defined in
+ <code>limit</code>. If user exited the native camera
+ application prematurely, <code>errorCB</code> must be invoked.</li>
+
+ <li>If a <code>CaptureVideoOptions</code> parameter was present,
+ and its <code>duration</code> attribute was defined,
+ <code>successCB</code> MUST be invoked after the video has
+ been captured for the number of milliseconds defined in
+ <code>duration</code>. If user exited the native camera
+ application prematurely, <code>errorCB</code> must be invoked.
+ </li>
+
+ </ol>
+
+ <p></p>
+
+ <dl class="parameters">
+ <dt>CaptureCB successCB </dt>
+ <dd>Function to call when the asynchronous operation completes </dd>
+
+ <dt>optional CaptureErrorCB? errorCB</dt>
+ <dd>Function to call when the asynchronous operation fails. This
+ parameter is OPTIONAL.</dd>
+
+ <dt>optional CaptureVideoOptions options </dt>
+ <dd>Image capture options. This parameter is OPTIONAL.</dd>
+ </dl>
+
+ </dd>
+ <dt>PendingOperation captureAudio () </dt>
+
+ <dd><p>Launch device native audio recorder application for
+ recording audio clip(s).</p>
+
+ <p>This method takes two or three arguments. When called, it
+ immediately returns a <a href="#pendingoperation-interface">
+ <code>PendingOperation</code></a> object and then asynchronously
+ start a <em>capture audio</em> process defined as follows:</p>
+
+ <p></p>
+
+ <ol>
+
+ <li>Start native audio recorder application. Allow end user to record
+ audio clip(s) and return.</li>
+
+ <li>If successful, invoke the associated <code>successCB</code>
+ with a <a href="#mediaarray-typedef"> <code>MediaArray</code></a>
+ argument. If the attempt fails, and the method was invoked with a
+ non-null <code>errorCallback</code> argument, this method must invoke
+ the <code>errorCallback</code> with a <a
+ href="#captureerror-interface"><code>CaptureError</code></a> object as
+ an argument.</li>
+
+ <li>If a <code>CaptureAudioOptions</code> parameter was present,
+ and its <code>limit</code> attribute was defined,
+ <code>successCB</code> MUST be invoked after the user has
+ captured a number of audio clips defined in
+ <code>limit</code>. If user exited the native camera
+ application prematurely, <code>errorCB</code> must be invoked.
+ </li>
+
+ </ol>
+
+ <p></p>
+
+ <dl class="parameters">
+ <dt>CaptureCB successCB </dt>
+ <dd>Function to call when the asynchronous operation completes </dd>
+
+ <dt>optional CaptureErrorCB? errorCB </dt>
+ <dd>Function to call when the asynchronous operation fails. This
+ parameter is OPTIONAL.</dd>
+
+ <dt>optional CaptureAudioOptions options </dt>
+ <dd>Audio capture options. This parameter is OPTIONAL.</dd>
+ </dl>
+ </dd></dl>
+ </section>
+
+ <section id="mediadata"><h3><a>MediaData</a> interface</h3>
+
+ <p><code>MediaData</code> captures a single photo, video or sound
+ captured by the device native capture application.</p>
+
+ <dl title="[NoInterfaceObject] interface MediaData" class="idl">
+ <dt>attribute DOMString uri</dt>
+
+ <dd>The uri attribute attribute specifies the path to the media file
+ taken by native application as a Uniform Resource Identifier (URI)
+ conforming to [[URI]].</dd>
+
+ <dt>attribute FormatData format </dt>
+
+ <dd>The format attribute represents the media <a
+ href="#formatdata-interface"><code>FormatData</code></a>
+ object.</dd></dl>
+
+ </section>
+
+ <section id="formatdata"><h3><a>FormatData</a> interface</h3>
+
+ <p><code>FormatData</code> captures format information of a media
+ file captured by the device native capture application.</p>
+
+ <dl title="[NoInterfaceObject] interface FormatData" class="idl">
+ <dt>attribute DOMString type</dt>
+ <dd>The type attribute represents the MIME type of the captured image,
+ video or sound. For example, a valid MIME type for JPEG images is
+ image/jpeg. A valid MIME type for WAV sound file is audio/x-wav.</dd>
+
+ <dt>attribute unsigned long height </dt>
+ <dd>The height attribute represents height of the image or video
+ in pixels. Not applicable for a sound clip.</dd>
+
+ <dt>attribute double duration </dt>
+ <dd>The duration attribute represents length of the video or sound
+ clip in milliseconds. Not applicable for an image.</dd>
+
+ <dt>attribute unsigned long width </dt>
+ <dd>The width attribute represents width of the image or video
+ in pixels. Not applicable for a sound clip.</dd>
+ </dl>
+
+ </section>
+
+ <section id="capturecallbak"><h3><a>CaptureCB</a> interface</h3>
+
+ <dl title="[Callback=FunctionOnly, NoInterfaceObject] interface CaptureCB" class="idl">
+ <dt>void onSuccess () </dt><dd>
+ <dl class="parameters"><dt>MediaArray capturedMedia </dt><dd>Sequence
+ of MediaData successfully captured by the device</dd>
+ </dd></dl>
+ </dd></dl>
+
+ </section>
+
+ <section id="mediaarray"><h3><a>MediaArray</a> typedef</h3>
+
+ <p>The <a>MediaArray</a> typedef represents a <code>sequence</code> of
+ <a href="#mediadata-interface"> <code>MediaData</code></a>
+ objects. </p>
+
+ <dl title="typedef sequence<MediaData> MediaArray" class="idl"></dl>
+
+ </section>
+
+ <section id="errorcallback"><h3><a>CaptureErrorCB</a> interface</h3>
+ <dl title="[Callback=FunctionOnly, NoInterfaceObject] interface CaptureErrorCB" class="idl">
+ <dt>void onError () </dt><dd>
+ <dl class="parameters"><dt>CaptureError error </dt><dd>The error
+ object of an unsuccessful capture asynchronous operation. </dd></dl>
+ </dd></dl>
+
+ </section>
+
+ <section id="captureerror"><h3><a>CaptureError</a> interface</h3>
+
+ <p>The <a>CaptureError</a> interface encapsulates all errors in the
+ Capture API. </p>
+
+ <p class="note">More error codes to be defined here. </p>
+
+ <dl title="[NoInterfaceObject] interface CaptureError" class="idl">
+ <dt>const unsigned short CAPTURE_INTERNAL_ERR = 0 </dt>
+ <dd>Camera or microphone failed to capture image or sound. </dd>
+ <dt>readonly attribute unsigned short code </dt>
+ <dd>An error code assigned by an implementation when an error has
+ occurred in Capture API processing.</dd>
+ </dl>
+
+ </section>
+
+ <section id="captureimageoptions"><h3><a>CaptureImageOptions</a> interface</h3>
+
+ <p>The <a>CaptureImageOptions</a> interface encapsulates all image
+ capture operation configuration options.</p>
+
+ <p class="note">Additional attributes proposed: <code>width</code>
+ and <code>height</code>.</p>
+
+ <dl title="[NoInterfaceObject] interface CaptureImageOptions" class="idl">
+ <dt>attribute unsigned long limit</dt>
+ <dd>Upper limit of images user can take.</dd>
+ </dl>
+
+ </section>
+
+ <section id="capturevideooptions"><h3><a>CaptureVideoOptions</a> interface</h3>
+
+ <dl title="[NoInterfaceObject] interface CaptureVideoOptions" class="idl">
+ <dt>attribute unsigned long limit</dt>
+ <dd>Upper limit of videos user can record.</dd>
+ <dt>attribute double duration</dt>
+ <dd>Maximum duration of a single video clip in milliseconds.</dd>
+ </dl>
+
+ </section>
+
+ <section id="captureaudiooptions"><h3><a>CaptureAudioOptions</a> interface</h3>
+ <p class="note">Additional attributes proposed: <code>duration</code>.</p>
+
+ <dl title="[NoInterfaceObject] interface CaptureAudioOptions" class="idl">
+ <dt>attribute unsigned long limit</dt>
+ <dd>Upper limit of sound clips user can record.</dd>
+ </dl>
+
+ </section>
+ </section>
+
+ <section id="pendingoperation"><h3><a>PendingOperation</a> interface</h3>
+
+ <p class="note">This may be a general interface for use throughout
+ all APIs. Included here for now for completion.</p>
+
+ <dl title="[NoInterfaceObject] interface PendingOperation" class="idl">
+ <dt>void cancel ()</dt>
+ <dd>Cancel/clear the pending asynchronous operation. </dd>
+ </dl>
+
+ </section>
+ </section>
+
+ <section id="formaccess">
+
+ <h2>Capture Input Selection</h2>
+
+ <p>In addition to programmable API, content can be acquired from
+ capture devices through a file-select control.</p>
+
+ <section id="capture">
+ <h2>Capture aware file-select control</h2>
+
+ <p>This section is non-normative.</p>
+
+ <p>If input element in the File Upload state [[HTML5]] contains
+ accept attribute with values <code>image/*</code>,
+ <code>sound/*</code>, or <code>video/*</code>, the user agent can
+ invoke a file picker that allows respectively the user to take a
+ picture, record a sound file, or record a video in addition to
+ selecting an existing file from the file system.</p>
+
+ <p>In case the user chooses to capture video, audio, or image
+ content, the user agent creates media files on the fly as
+ specified in [[HTML5]].</p>
+
+ <pre class="example sh_javascript_dom"><input id="cameraInput" type="file" accept="image/*"> </pre>
+
+ <p>In trusted environments the click event of file input element
+ can be synthesised as follows:</p>
+
+ <pre class="example sh_javascript_dom">
+
+<input id="cameraInput" onchange="successCB();" type="file" accept="image/*">
<script>
@@ -351,9 +526,15 @@
</dl>
-<p>Conforming user agents MUST provide the user a file picker from which it is possible to select any of the available capture devices in addition to possibility to select one or more files from the file system.</p>
+<p>Conforming user agents MUST provide the user a file picker from
+which it is possible to select any of the available capture devices in
+addition to possibility to select one or more files from the file
+system.</p>
-<p>If a user selects camera device, the <code>FileList</code> object that represents the currently selected files in the input element in the File Upload state MUST contain one or more <code>ViewFinder</code> objects instead of <code>File</code> objects as in [[FILE-API]].</p>
+<p>If a user selects camera device, the <code>FileList</code> object
+that represents the currently selected files in the input element in
+the File Upload state MUST contain one or more <code>ViewFinder</code>
+objects instead of <code>File</code> objects as in [[FILE-API]].</p>
<pre class="example example sh_javascript_dom">
@@ -427,65 +608,140 @@
<li>MUST support asynchronous, cancellable capture </li>
</ul>
<div class="issue">
-<p>If the user requests a given capture size which isn't available, do we refuse or do we fall back? If the latter (which is likely) what is the algorithm that is used to find the fallback? It could be (given a request for 1000x50):
+
+<p>If the user requests a given capture size which isn't available, do
+we refuse or do we fall back? If the latter (which is likely) what is
+the algorithm that is used to find the fallback? It could be (given a
+request for 1000x50):
+
</p>
<ul>
-<li>the camera's preferred default </li><li>500x100 (closest number of pixels) </li><li>1000x700 (closest longest side) </li><li>2000x100 (closest ratio) </li></ul>
+
+<li>the camera's preferred default </li><li>500x100 (closest number of
+pixels) </li><li>1000x700 (closest longest side) </li><li>2000x100
+(closest ratio) </li></ul>
+
<p></p>
</div>
-<p class="issue">We could very easily get bogged down in specifying camera capabilities and format feature variants — how do we decide which ones are reasonably in?
+
+<p class="issue">We could very easily get bogged down in specifying
+camera capabilities and format feature variants — how do we
+decide which ones are reasonably in?
+
</p>
<div class="issue">
-<p>We probably need to support more than 1 camera. On some of the newer device, there is a camera point at the user and
-another on the other side pointing at the subject. This allows for such usage as see-what-I-see.
-</p>
+
+<p>We probably need to support more than 1 camera. On some of the
+newer device, there is a camera point at the user and another on the
+other side pointing at the subject. This allows for such usage as
+see-what-I-see.</p>
+
</div>
</section>
<section>
+
<h3>Use cases</h3>
-<p>This section contains a set of use cases collected for the Capture API. Note that this section might be removed in future versions of the document.
+
+<p>This section contains a set of use cases collected for the Capture
+API. Note that this section might be removed in future versions of the
+document.
+
</p>
<h4>Picture Capture and Picture upload</h4>
-<p>A (web-based) camera application that allow the user to capture image with and without preview mode using the device camera capability.
-Also allow the user to capture multiple images in burst mode and upload the image(s) to a server using XHR.
+
+<p>A (web-based) camera application that allow the user to capture
+image with and without preview mode using the device camera
+capability. Also allow the user to capture multiple images in burst
+mode and upload the image(s) to a server using XHR.
</p>
+
<div class="issue">
- <p>The image is returned as URI from captureImage() callback? How do we XHR upload? Do we need the FileAPI or is there a need to return the image (captured object) as binary data?</p>
+
+<p>The image is returned as URI from captureImage() callback? How do
+we XHR upload? Do we need the FileAPI or is there a need to return
+the image (captured object) as binary data?</p>
+
</div>
<h4>Panorama Image Capture</h4>
-<p>A (web-based) camera application that allow the user to capture panorama images with and without preview mode using the device camera capability.
-When the user select panorama mode, the view finder displays an indication that it is ready to take the 1st image of 3.
-the user points the device starting from the left and presses the Take button. The device takes the image indicated
-by an alert, then goes back to take mode for the next image in the sequence.
-The view finder displays a 1/8 overlay of previous image on the left side so the user can line up for the next image.
-After taking all 3 images that makes up the panorama picture, the device displays the picture on the screen for a
-second before going back to the view finder mode.
+
+<p>A (web-based) camera application that allow the user to capture
+panorama images with and without preview mode using the device camera
+capability. When the user select panorama mode, the view finder
+displays an indication that it is ready to take the 1st image of 3.
+the user points the device starting from the left and presses the Take
+button. The device takes the image indicated by an alert, then goes
+back to take mode for the next image in the sequence. The view finder
+displays a 1/8 overlay of previous image on the left side so the user
+can line up for the next image. After taking all 3 images that makes
+up the panorama picture, the device displays the picture on the screen
+for a second before going back to the view finder mode.
</p>
+
<h4>Video chat</h4>
-<p>The use case is to be able to write a web app that implements a voice/video chat client. This could be as part of an instant messaging client, or might be a standalone videophone or 'telephone'. Another example might be an online 'chat with customer service'
- link on the web site that downloaded the web app that allowed the customer to do this directly.
+
+<p>The use case is to be able to write a web app that implements a
+ voice/video chat client. This could be as part of an instant
+ messaging client, or might be a standalone videophone or
+ 'telephone'. Another example might be an online 'chat with customer
+ service' link on the web site that downloaded the web app that
+ allowed the customer to do this directly.
</p>
+
<h5>Discussion</h5>
-<p>Video output can be handled with the <code><video></code> tag. However, video input is not so easy as there is no obvious way to pass captured video in real time to the server. You might think that you could use the preview URL as proposed in one API as a way, but there
- is no obvious way to pass the data coming out of this URL down (for example) a websocket.
+
+<p>Video output can be handled with the <code><video></code>
+ tag. However, video input is not so easy as there is no obvious way
+ to pass captured video in real time to the server. You might think
+ that you could use the preview URL as proposed in one API as a way,
+ but there is no obvious way to pass the data coming out of this URL
+ down (for example) a websocket.
</p>
-<p>The approach of rendering the preview into a <code><canvas></code> and then scraping the canvas, re-encoding the data and transmitting it seems too ugly (and too inefficient) to be useful. The rendering approach also doesn't work for the associated audio stream. Worse,
- the preview data stream might not include the audio anyway. </p>
-<p>An ideal approach would be to define a websocket like interface onto the camera/microphone (it might even be as simple as defining a method to get a web sockets URL for the camera/microphone). Another alternative (which would cause more upheaval) would be
- to add the websocket read/write interface onto XmlHttpRequest and then have the camera expose an HTTP URL for the full audio/video data stream.
+
+<p>The approach of rendering the preview into a
+ <code><canvas></code> and then scraping the canvas, re-encoding
+ the data and transmitting it seems too ugly (and too inefficient) to
+ be useful. The rendering approach also doesn't work for the
+ associated audio stream. Worse, the preview data stream might not
+ include the audio anyway. </p>
+
+<p>An ideal approach would be to define a websocket like interface
+ onto the camera/microphone (it might even be as simple as defining a
+ method to get a web sockets URL for the camera/microphone). Another
+ alternative (which would cause more upheaval) would be to add the
+ websocket read/write interface onto XmlHttpRequest and then have the
+ camera expose an HTTP URL for the full audio/video data stream.
</p>
+
<h4>Web cam</h4>
-<p>A (web-based) surveillance application that would allow the user to survey their property remotely. The camera would allow for
-some type of control such as moving the camera left, right, up and down. Another usage would allow for the surveillance web application
-to monitor for movement and trigger a notification such as email or alert to the user</p>
+
+<p>A (web-based) surveillance application that would allow the user to
+survey their property remotely. The camera would allow for some type
+of control such as moving the camera left, right, up and down. Another
+usage would allow for the surveillance web application to monitor for
+movement and trigger a notification such as email or alert to the
+user</p>
+
<h4>Voice search</h4>
-<p>A (web-based) search application might offer the user to speak the search query into the device, e.g. while holding a push-to-talk button or triggered by a proximity sensor (use case for sensor API). The users utterance has to be recorded (captured) and
- may be sent over the network to a network based speech recognizer. </p>
+
+<p>A (web-based) search application might offer the user to speak the
+ search query into the device, e.g. while holding a push-to-talk
+ button or triggered by a proximity sensor (use case for sensor
+ API). The users utterance has to be recorded (captured) and may be
+ sent over the network to a network based speech recognizer. </p>
+
<h5>Discussion</h5>
-<p>To avoid latency while sending the captured voice sample to the network based speech recognizer, the voice should be recorded in a compressed format. The API should allow to select a compression format.
+
+<p>To avoid latency while sending the captured voice sample to the
+network based speech recognizer, the voice should be recorded in a
+compressed format. The API should allow to select a compression
+format.
+
</p>
<h4>Voice memo</h4>
-<p>A (web-based) voice recorder application which allow the user to record a memo for later playback.</p>
+
+<p>A (web-based) voice recorder application which allow the user to
+record a memo for later playback.</p>
+
</section>
<section id="related">
<h2>Related documents</h2>
@@ -498,14 +754,21 @@
</section>
<section id="future">
<h2>Features for Future Consideration</h2>
-<p>This is a list of features that have been discussed with respect to this version of the API but for which it has been decided that if they are included it will be in a future revision.
+
+<p>This is a list of features that have been discussed with respect to
+this version of the API but for which it has been decided that if they
+are included it will be in a future revision.
+
</p>
<ul>
<li>... </li></ul>
</section>
<section id="ack">
<h2>Acknowledgements</h2>
-<p>Many thanks to Google, Nokia, and OMTP BONDI who provided the initial input into this specification.
+
+<p>Many thanks to Google, Nokia, and OMTP BONDI who provided the
+initial input into this specification.
+
</p>
</section>
</body>
Received on Monday, 22 March 2010 16:33:11 UTC