- From: Ilkka Oksanen via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 06 Jul 2010 13:33:51 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/camera
In directory hutz:/tmp/cvs-serv25168
Modified Files:
Overview.html
Added Files:
Level-2-placeholder.html Overview-API.html
Log Message:
Started Media Capture API restructuring. Will continue tomorrow.
--- NEW FILE: Level-2-placeholder.html ---
<!DOCTYPE html>
<html>
<head>
<title>The Media Capture API - level 2 placeholder</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "unofficial",
shortName: "capture-level-2",
editors: [{name: "Dzung D Tran", company: "Intel"},
{name: "Ilkka Oksanen", company: "Nokia"},
{name: "Ingmar Kliche", company: "Deutsche Telekom"},
//{name: "Dominique Hazaël-Massieux", company: "W3C"}
],
// publishDate: "2009-08-06",
// previousPublishDate: "1977-03-15",
// edDraftURI: "http://dev.w3.org/2009/dap/camera-req/",
// lcEnd: "2009-08-05",
};
</script>
<script src='../common/config.js' class='remove'></script>
</head>
<body>
<section id="abstract">
<p>This is a temporary document for storing potential specification text for level 2 of Media Capture API.</p>
</section>
<section id="viewfinder-interface">
<h3><a>ViewFinder</a> interface</h3>
<p>This interface represents a camera viewfinder. It inherits from
<code>File</code> [[FILE-API]] and provides a method to embed a
viewfinder to web content.</p>
<dl title='[NoInterfaceObject] interface ViewFinder : File' class='idl'>
<dt>void startCapture ()</dt>
<dd>
<p>
Starts the capture process.
</p>
<dl class='parameters'>
<dt>Blob data</dt>
<dd>
The blob to write.
</dd>
</dl>
</dd>
<dt>void stopCapture ()</dt>
<dd>
<p>
Stops the capture process.
</p>
</dd>
</dl>
<dt>PendingOperation getViewFinder () </dt>
<dd>
<p>This method takes one or two arguments. When called, it
immediately returns a <a
href="#pendingoperation"><code>PendingOperation</code></a>
object and then tries asynchronously to return the ViewFinder object of the
active capture device selected by the system or user.</p>
<p class='note'>User consent must be verified.</p>
<p>If successful, invokes the associated <code>ViewFinderCB</code>
with a <a href="#viewfinder-interface"> <code>ViewFinder</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>errorCB</code> with a <a
href="#captureerror"><code>CaptureError</code></a> object as
an argument.</p>
<dl class="parameters">
<dt>ViewFinderCB successCB </dt>
<dd>Function to call when the asynchronous operation completes </dd>
<dt>optional ViewFinderErrorCB? errorCB </dt>
<dd>Function to call when the asynchronous operation
fails. This parameter is OPTIONAL.</dd>
</dl>
</dd>
</dl>
</section>
<section id="viewfindercallback"><h3><a>ViewFinderCB</a> interface</h3>
<dl title="[Callback=FunctionOnly, NoInterfaceObject] interface ViewFinderCB" class="idl">
<dt>void onSuccess () </dt><dd>
<dl class="parameters"><dt>ViewFinder viewfinder </dt><dd>The
ViewFinder object of the selected capture device.</dd></dl>
</dd></dl>
</section>
<section id="viewfindererrorcallback"><h3><a>ViewFinderErrorCB</a> interface</h3>
<dl title="[Callback=FunctionOnly, NoInterfaceObject] interface ViewFinderErrorCB" class="idl">
<dt>void onError () </dt><dd>
<dl class="parameters"><dt>CaptureError error</dt><dd> The error
object of an unsuccessful asynchronous viewfinder acquisition operation. </dd></dl>
</dd></dl>
</section>
<section id="viewfinder">
<h2>ViewFinder aware file-select control</h2>
<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 <code>ViewFinder</code>
object instead of <code>File</code> objects as in [[FILE-API]].</p>
<pre class="example example sh_javascript_dom">
<script>
function getVideo () {
var inp = document.createElement("input");
inp.type = "file";
inp.accept = "video/*";
inp.onchange = function () { setupVideo(this.files[0]); };
// this is only possible in trusted environments
// the click event cannot be synthetized by default
inp.click();
}
var blob;
function setupVideo (vf) {
document.getElementById("my-video").src = vf.URL;
var bb = new BlobBuilder();
blob = bb.getBlob();
document.getElementById("start").onclick = function () { vf.startCapture(bb.getBlob()); }
document.getElementById("stop").onclick = function () { vf.stopCapture(); }
document.getElementById("send").onclick = function () { send(); }
}
function send () {
if (!blob) {
alert("You didn't capture anything!")
return;
}
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://my-server/video-upload");
xhr.onreadystatechange = function () {
if (xhr.readyState == 4 && xhr.status == 200) alert("Video uploaded!");
}
xhr.send(blob);
}
</script>
<button onclick='getVideo();'>Film your face!</button>
<video id='my-video'></video>
<button id='start'>Start</button>
<button id='stop'>Stop</button>
<button id='send'>Upload</button>
</pre>
</section>
<!--************************************* /Requirements ******************************************-->
</body>
</html>
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/camera/Overview.html,v
retrieving revision 1.65
retrieving revision 1.66
diff -u -d -r1.65 -r1.66
--- Overview.html 24 Jun 2010 04:48:29 -0000 1.65
+++ Overview.html 6 Jul 2010 13:33:49 -0000 1.66
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
- <title>The Media Capture API</title>
+ <title>Capture Input Selection</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script class='remove'>
@@ -43,56 +43,6 @@
<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">
-
-function success(data) {
- var container = document.createElement("div");
- document.body.appendChild(container);
-
- for (var i in data) {
- var img = document.createElement("img");
- img.src = data[i].uri;
- container.appendChild(img);
- }
-}
-
-function error(err) {
- alert(err.message + " (" + err.code + ")");
-}
-
-navigator.device.captureImage(success, error, { maxNumberOfMediaFiles: 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;
-
-for (var key in formats) {
- summary += key + ": " + formats[key] + "\n";
-}
-
-alert(summary);
-
- </pre>
- </div>
- </section>
</section>
<section id="security">
@@ -125,227 +75,6 @@
<section id="api">
<h2>API Description</h2>
- <section>
- <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>
-
- <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 title="[Supplemental, NoInterfaceObject] interface Capture"
- class="idl"><dt>readonly attribute FormatData[]
- supportedImageFormats</dt>
-
- <dd>An array of FormatData objects which contains image sizes
- and formats supported by the hosting device camera.</dd>
-
- <dt>readonly attribute FormatData[]
- supportedVideoFormats </dt>
- <dd>An array of FormatData objects which contains video
- resolutions and formats supported by the hosting device
- camera.</dd>
-
- <dt>readonly attribute FormatData[]
- supportedAudioFormats</dt>
- <dd>An array 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"><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"> <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"><code>CaptureError</code></a> object
- as an argument.</li>
-
- <li>If a <code>CaptureImageOptions</code> parameter was present,
- and its <code>maxNumberOfMediaFiles</code> attribute was defined,
- <code>successCB</code> MUST be invoked after the user has
- captured a number of images defined in <code>maxNumberOfMediaFiles</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 CaptureImageOptions options </dt>
- <dd>Image capture options. This parameter is OPTIONAL.</dd>
- </dl>
-
- </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"><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"> <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"><code>CaptureError</code></a> object as
- an argument.</li>
-
- <li>If a <code>CaptureVideoOptions</code> parameter was present, and
- its <code>maxNumberOfMediaFiles</code> attribute was defined,
- <code>successCB</code> MUST be invoked after the user has
- captured a number of video clips defined in
- <code>maxNumberOfMediaFiles</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">
- <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"> <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"><code>CaptureError</code></a> object as
- an argument.</li>
-
- <li>If a <code>CaptureAudioOptions</code> parameter was present,
- and its <code>maxNumberOfMediaFiles</code> attribute was defined,
- <code>successCB</code> MUST be invoked after the user has
- captured a number of audio clips defined in
- <code>maxNumberOfMediaFiles</code>. If user exited the native audio recorder
- 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>
-
-
- <dt>PendingOperation getViewFinder () </dt>
- <dd>
-
- <p>This method takes one or two arguments. When called, it
- immediately returns a <a
- href="#pendingoperation"><code>PendingOperation</code></a>
- object and then tries asynchronously to return the ViewFinder object of the
- active capture device selected by the system or user.</p>
-
- <p class='note'>User consent must be verified.</p>
-
- <p>If successful, invokes the associated <code>ViewFinderCB</code>
- with a <a href="#viewfinder-interface"> <code>ViewFinder</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>errorCB</code> with a <a
- href="#captureerror"><code>CaptureError</code></a> object as
- an argument.</p>
-
- <dl class="parameters">
- <dt>ViewFinderCB successCB </dt>
- <dd>Function to call when the asynchronous operation completes </dd>
-
- <dt>optional ViewFinderErrorCB? errorCB </dt>
- <dd>Function to call when the asynchronous operation
- fails. This parameter is OPTIONAL.</dd>
- </dl>
- </dd>
- </dl>
- </section>
-
<section id="mediafile"><h3><a>MediaFile</a> interface</h3>
<p><code>MediaFile</code> captures a single photo, video or sound
@@ -401,161 +130,15 @@
</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 MediaFile 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="#mediafile"> <code>MediaFile</code></a>
- objects. </p>
-
- <dl title="typedef sequence<MediaFile> 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="viewfindercallback"><h3><a>ViewFinderCB</a> interface</h3>
- <dl title="[Callback=FunctionOnly, NoInterfaceObject] interface ViewFinderCB" class="idl">
- <dt>void onSuccess () </dt><dd>
- <dl class="parameters"><dt>ViewFinder viewfinder </dt><dd>The
- ViewFinder object of the selected capture device.</dd></dl>
- </dd></dl>
-
- </section>
-
- <section id="viewfindererrorcallback"><h3><a>ViewFinderErrorCB</a> interface</h3>
- <dl title="[Callback=FunctionOnly, NoInterfaceObject] interface ViewFinderErrorCB" class="idl">
- <dt>void onError () </dt><dd>
- <dl class="parameters"><dt>CaptureError error</dt><dd> The error
- object of an unsuccessful asynchronous viewfinder acquisition 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 maxNumberOfMediaFiles</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 maxNumberOfMediaFiles</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 maxNumberOfMediaFiles</dt>
- <dd>Upper limit of sound clips user can record.</dd>
- </dl>
-
- </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 id="viewfinder-interface">
- <h3><a>ViewFinder</a> interface</h3>
-
- <p>This interface represents a camera viewfinder. It inherits from
- <code>File</code> [[FILE-API]] and provides a method to embed a
- viewfinder to web content.</p>
-
- <dl title='[NoInterfaceObject] interface ViewFinder : File' class='idl'>
-
- <dt>void startCapture ()</dt>
- <dd>
- <p>
- Starts the capture process.
- </p>
- <dl class='parameters'>
- <dt>Blob data</dt>
- <dd>
- The blob to write.
- </dd>
- </dl>
- </dd>
- <dt>void stopCapture ()</dt>
- <dd>
- <p>
- Stops the capture process.
- </p>
- </dd>
-
- </dl>
-
- </section>
</section>
<section id="formaccess">
+ <h2>Capture aware file-select control</h2>
- <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 class='note'>
+ Add 'source' attribute and make this section normative.
+ </p>
<p>This section is non-normative.</p>
@@ -594,77 +177,6 @@
</pre>
</section>
-<section id="viewfinder">
-<h2>ViewFinder aware file-select control</h2>
-
-<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 <code>ViewFinder</code>
-object instead of <code>File</code> objects as in [[FILE-API]].</p>
-
-<pre class="example example sh_javascript_dom">
- <script>
-
- function getVideo () {
- var inp = document.createElement("input");
- inp.type = "file";
- inp.accept = "video/*";
- inp.onchange = function () { setupVideo(this.files[0]); };
- // this is only possible in trusted environments
- // the click event cannot be synthetized by default
- inp.click();
- }
-
- var blob;
-
- function setupVideo (vf) {
- document.getElementById("my-video").src = vf.URL;
- var bb = new BlobBuilder();
- blob = bb.getBlob();
- document.getElementById("start").onclick = function () { vf.startCapture(bb.getBlob()); }
- document.getElementById("stop").onclick = function () { vf.stopCapture(); }
- document.getElementById("send").onclick = function () { send(); }
- }
-
- function send () {
- if (!blob) {
- alert("You didn't capture anything!")
- return;
- }
- var xhr = new XMLHttpRequest();
- xhr.open("GET", "http://my-server/video-upload");
- xhr.onreadystatechange = function () {
- if (xhr.readyState == 4 && xhr.status == 200) alert("Video uploaded!");
- }
- xhr.send(blob);
- }
- </script>
-
- <button onclick='getVideo();'>Film your face!</button>
- <video id='my-video'></video>
- <button id='start'>Start</button>
- <button id='stop'>Stop</button>
- <button id='send'>Upload</button>
-</pre>
-
-</section>
-
-</section>
-
-<section class='appendix' id="related">
-<h2>Related documents</h2>
-<p>The API described in this document took inspiration from the following documents:</p>
-<ul>
-<li><a href="http://code.google.com/p/gears/wiki/CameraAPI">Google Camera API</a>
-</li><li><a href="http://bondi.omtp.org/1.0/apis/camera.html">BONDI 1.1 camera API</a>
-</li><li><a href="http://lists.w3.org/Archives/Public/public-device-apis/2009Apr/att-0001/camera.html">Nokia Camara API</a>
-</li></ul>
-</section>
<section class='appendix' id="uiexamples">
<h2>User Interface Examples</h2>
@@ -685,13 +197,5 @@
<ul>
<li>... </li></ul>
</section>
-<section class='appendix' id="ack">
-<h2>Acknowledgements</h2>
-
-<p>Many thanks to Google, Nokia, and OMTP BONDI who provided the
-initial input into this specification.
-
-</p>
-</section>
</body>
</html>
--- NEW FILE: Overview-API.html ---
<!DOCTYPE html>
<html>
<head>
<title>The Media Capture API</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "FPWD",
shortName: "capture-api",
editors: [{name: "Dzung D Tran", company: "Intel"},
{name: "Ilkka Oksanen", company: "Nokia"},
{name: "Ingmar Kliche", company: "Deutsche Telekom"},
//{name: "Dominique Hazaël-Massieux", company: "W3C"}
],
publishDate: "2010-04-01",
// previousPublishDate: "1977-03-15",
edDraftURI: "http://dev.w3.org/2009/dap/camera/",
// lcEnd: "2009-08-05",
};
</script>
<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>
<section id="sotd">
<p>This document represents the early consensus of the group on
the scope and features of the proposed Capture
API. Issues and editors notes in the document highlight some of
the points on which the group is still working and would
particularly like to get feedback.</p>
</section>
<section>
<h2>Introduction</h2>
<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">
function success(data) {
var container = document.createElement("div");
document.body.appendChild(container);
for (var i in data) {
var img = document.createElement("img");
img.src = data[i].uri;
container.appendChild(img);
}
}
function error(err) {
alert(err.message + " (" + err.code + ")");
}
navigator.device.captureImage(success, error, { maxNumberOfMediaFiles: 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;
for (var key in formats) {
summary += key + ": " + formats[key] + "\n";
}
alert(summary);
</pre>
</div>
</section>
</section>
<section id="security">
<h2>Security and Privacy Considerations</h2>
<p class='note'>
<strong>The overall architecture for addressing privacy in DAP is still
under construction. As it is finalized, there may be changes made to
this API to reflect requirements or support for privacy-related
functionality.</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>
<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>
</section>
<section id="api">
<h2>API Description</h2>
<section>
<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>
<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 title="[Supplemental, NoInterfaceObject] interface Capture"
class="idl"><dt>readonly attribute FormatData[]
supportedImageFormats</dt>
<dd>An array of FormatData objects which contains image sizes
and formats supported by the hosting device camera.</dd>
<dt>readonly attribute FormatData[]
supportedVideoFormats </dt>
<dd>An array of FormatData objects which contains video
resolutions and formats supported by the hosting device
camera.</dd>
<dt>readonly attribute FormatData[]
supportedAudioFormats</dt>
<dd>An array 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"><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"> <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"><code>CaptureError</code></a> object
as an argument.</li>
<li>If a <code>CaptureImageOptions</code> parameter was present,
and its <code>maxNumberOfMediaFiles</code> attribute was defined,
<code>successCB</code> MUST be invoked after the user has
captured a number of images defined in <code>maxNumberOfMediaFiles</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 CaptureImageOptions options </dt>
<dd>Image capture options. This parameter is OPTIONAL.</dd>
</dl>
</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"><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"> <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"><code>CaptureError</code></a> object as
an argument.</li>
<li>If a <code>CaptureVideoOptions</code> parameter was present, and
its <code>maxNumberOfMediaFiles</code> attribute was defined,
<code>successCB</code> MUST be invoked after the user has
captured a number of video clips defined in
<code>maxNumberOfMediaFiles</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">
<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"> <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"><code>CaptureError</code></a> object as
an argument.</li>
<li>If a <code>CaptureAudioOptions</code> parameter was present,
and its <code>maxNumberOfMediaFiles</code> attribute was defined,
<code>successCB</code> MUST be invoked after the user has
captured a number of audio clips defined in
<code>maxNumberOfMediaFiles</code>. If user exited the native audio recorder
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="mediafile"><h3><a>MediaFile</a> interface</h3>
<p><code>MediaFile</code> captures a single photo, video or sound
captured by the device native capture application. It inherits
from <code>File</code> [[FILE-API]]</p>
<dl title="[NoInterfaceObject] interface MediaFile : File" class="idl">
<dt>attribute FormatData format </dt>
<dd>The format attribute represents the format information of <a
href="#formatdata"><code>MediaFile</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 images is
image/jpeg. A valid MIME type for audio files is audio/x-speex or audio/ogg.</dd>
<dt>attribute DOMString codecs</dt>
<dd>The type attribute is not enough to determine the format of the
content since it only specifies the container type. The codecs attribute
represents the actual format that the audio and video of the content.
The codecs attribute must conforms to the [[RFC4281]].
For example, a valid value for H.263 video and AAC low
complexity would be codecs="s263, mp4a.40.2".</dd>
<dt>attribute long bitrate </dt>
<dd>The codecs attribute only specifies the profile and level of the encoded content
which doesn't specify the actual bitrate. It only specifies the maximum encoded
bitrate, thus this bitrate attribute is the average bitrate of the content. In the case
of a image this attribute has value 0.</dd>
<dt>attribute unsigned long height </dt>
<dd>The height attribute represents height of the image or video
in pixels. In the case of a sound clip this attribute has value 0.</dd>
<dt>attribute unsigned long width </dt>
<dd>The width attribute represents width of the image or video
in pixels. In the case of a sound clip this attribute has value 0.</dd>
<dt>attribute double duration </dt>
<dd>The duration attribute represents length of the video or sound
clip in milliseconds. In the case of a image this attribute has value 0.</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 MediaFile 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="#mediafile"> <code>MediaFile</code></a>
objects. </p>
<dl title="typedef sequence<MediaFile> 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 maxNumberOfMediaFiles</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 maxNumberOfMediaFiles</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 maxNumberOfMediaFiles</dt>
<dd>Upper limit of sound clips user can record.</dd>
</dl>
</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>See the <a href="#uiexamples">User Interface Examples</a> appendix for the illustration.
<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>
function successCB() {
// Read the image using file-reader or submit the form
}
document.getElementById('cameraInput').click();
</script>
</pre>
</section>
</section>
<section class='appendix' id="related">
<h2>Related documents</h2>
<p>The API described in this document took inspiration from the following documents:</p>
<ul>
<li><a href="http://code.google.com/p/gears/wiki/CameraAPI">Google Camera API</a>
</li><li><a href="http://bondi.omtp.org/1.0/apis/camera.html">BONDI 1.1 camera API</a>
</li><li><a href="http://lists.w3.org/Archives/Public/public-device-apis/2009Apr/att-0001/camera.html">Nokia Camara API</a>
</li></ul>
</section>
<section class='appendix' id="uiexamples">
<h2>User Interface Examples</h2>
<p>Capture API aware file picker might render as:
<p><img alt="A File picker with camera support" src="capture-api-file-picker-concept.png"></p>
</section>
<section class='appendix' 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>
<ul>
<li>... </li></ul>
</section>
<section class='appendix' id="ack">
<h2>Acknowledgements</h2>
<p>Many thanks to Google, Nokia, and OMTP BONDI who provided the
initial input into this specification.
</p>
</section>
</body>
</html>
Received on Tuesday, 6 July 2010 13:33:55 UTC