Overview.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">

<html lang=en>
 <head profile="http://dublincore.org/documents/2008/08/04/dc-html/ ">
  <title>VHS API</title>

  <link href="http://purl.org/dc/terms/" rel=schema.dcterms>
  <link href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright"
   rel=dcterms.rights>
  <meta content="VHS API" name=dcterms.title>
  <meta content=text name=dcterms.type>
  <meta content=2013-02-20 name=dcterms.issued>
  <meta content="text/html; charset=utf-8" http-equiv=Content-Type>
  <style type="text/css">
    table.animatable-properties {
      border-collapse: collapse;
    }
    table.animatable-properties td {
      padding: 0.2em 1em;
      border: 1px solid black;
    }
    div.prod { margin: 1em 2em; }
  </style>
  <link href="http://www.w3.org/StyleSheets/TR/w3c-unofficial.css" rel=stylesheet
   type="text/css">

 <body>
  <div class=head> <!--begin-logo-->
   <p><a href="http://www.w3.org/"><img alt=W3C height=48
    src="http://www.w3.org/Icons/w3c_home" width=72></a> <!--end-logo-->

   <h1>Web VHS API</h1>

   <h2 class="no-num no-toc" id=longstatus-date>Unofficial Draft 1 April
    1989</h2>

   <dl>
    <dt>This version:

    <!-- FIXME: Fix the links. -->
    <dd> <a href="http://dev.w3.org/csswg/vcr-api/">http://dev.w3.org/vcr-api/</a>

    <dt>Latest version:

    <dd><a href="http://dev.w3.org/TR/vcr-api/">
     http://www.w3.org/TR/vcr-api/</a>

    <dt id=editors-list>Editors:

    <dd><a href="mailto:alexis@webkit.org">Alexis Menard</a>
      
    <dd><a href="mailto:benjamin@webkit.org">Benjamin Poulain</a>

    <dt>Discussion:

    <dd><a
     href="http://lists.w3.org/Archives/Public/www-style/">tape-wg@w3.org</a>
     with subject line “<kbd>[vhs-api] <var>… message topic
     …</var></kbd>”

    <dt>Test suite:

    <dd>none yet
   </dl>
   <!--begin-copyright-->
   <p class=copyright><a
    href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright"
    rel=license>Copyright</a> © 2013 <a href="http://www.w3.org/"><abbr
    title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a
    href="http://www.csail.mit.edu/"><abbr
    title="Massachusetts Institute of Technology">MIT</abbr></a>, <a
    href="http://www.ercim.eu/"><abbr
    title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>,
    <a href="http://www.keio.ac.jp/">Keio</a>, <a
    href="http://ev.buaa.edu.cn/">Beihang</a>), All Rights Reserved. W3C <a
    href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
    <a
    href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
    and <a
    href="http://www.w3.org/Consortium/Legal/copyright-documents">document
    use</a> rules apply.</p>
   <!--end-copyright-->
   <hr title="Separator for header">
  </div>

  <h2 class="no-num no-toc" id=abstract>Abstract</h2>
  <p>
  The Web VHS API specification defines new interfaces to handle <i>Video Home System</i>.
  The specification covers the interactive playing of multimedia content from VHS,
  and the complete support for uploading cat videos to online video services.
  </p>
  
  <h2 class="no-num no-toc" id=status>Status of this document</h2>
  <!--begin-status-->

  <p>This is a working draft. It is provided for
   discussion only and may change at any moment. Its publication here does
   not imply endorsement of its contents by W3C. Don't cite this document
   other than as work in progress.

  <p>The (<a
   href="http://lists.w3.org/Archives/Public/www-style/">archived</a>) public
   mailing list <a
   href="mailto:tape-wg@w3.org?Subject=%vhs-api%5D%20PUT%20SUBJECT%20HERE">
   tape-wg@w3.org</a> (see <a
   href="http://www.w3.org/Mail/Request">instructions</a>) is preferred for
   discussion of this specification. When sending e-mail, please put the text
   “vhs-api” in the subject, preferably like this:
   “[<!---->vhs-api<!---->] <em>…summary of comment…</em>”

  <h2 class="no-num no-toc" id=contents>Table of Contents</h2>
  <!--begin-toc-->

  <ul class=toc>
   <li><a href="#introduction"><span class=secno>1. </span>Introduction</a>

   <li><a href="#conformance"><span class=secno>2. </span>Conformance</a>
   <li><a href="#privacy"><span class=secno>3. </span>Privacy</a>
   <li><a href="#access"><span class=secno>4. </span>Obtaining Access to VHS Interfaces Available to the User Agent</a>
   <li><a href="#accessInt"><span class=secno>5. </span>VHSAccess Interface</a>
   <li><a href="#VHSInput"><span class=secno>6. </span>VHSInput Interface</a>
   <li><a href="#VHSOutput"><span class=secno>7. </span>VHSOutput Interface</a>
   <li><a href="#Examples"><span class=secno>8. </span>Examples</a>
   <li><a href="#acknowledgments"><span class=secno>9.
    </span>Acknowledgments</a>

   <li><a href="#references"><span class=secno>10. </span>References</a>
    <ul class=toc>
     <li class=no-num><a href="#normative-references">Normative
      references</a>

     <li class=no-num><a href="#other-references">Other references</a>
    </ul>

   <li class=no-num><a href="#property-index">Property index</a>

   <li class=no-num><a href="#index">Index</a>
  </ul>
  <!--end-toc-->

  <h2 id=introduction><span class=secno>1. </span>Introduction</h2>

  <p><em>This section is not normative.</em>

  <p>
  The Video Home System (better known by its acronym VHS) is a consumer-level analog recording videotape-based cassette standard.
  VHS has been very successful for video playing and recording and over 100 millions VHS players have been sold since the introduction of the format.
  </p>
  <p>
  In recent years, the success of web browsers have been hampered by the lack of VHS support.
  This specification aims at defining VHS support for the web, and gives web applications the same kind
  of capabilities expected from native multimedia solutions.
  </p>


  <p> This document introduces new HTML and CSS features to enable the use of <em>video
    cassette</em>. These are intended to bring back the joy of watching your old tapes,
    rewinding your cassette and enjoying the bleeding edge technology from a supporting
    User Agent (such as smartphones or computers).
	<p> 
  The Tape Working Group discarded on purpose the Betamax protocol as its usage seems to be marginal.
  </p> 
  <h2 id=Conformance><span class=secno>2. </span><a
   id=Conformance->Conformance</a></h2>
	As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
	The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
	This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
	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.
  
  <h2 id=privacy><span class=secno>3. </span><a
   id=security->Privacy considerations</a></h2>
  There are privacy concerns with adding the Web VHS API to the web platform:
  <ol>
  	<li>Allowing the enumeration of the user's VHS interfaces is a potential target for fingerprinting.</li>
    <li>A malicious website could read the content of a tape without the user consent.</li>
  </ol>
  <p>
  To address the issues, the specifications follows the state of the art privacy strategy:
  "If you have something that you don't want anyone to know, maybe you shouldn't be doing it in the first place."</p>
  
   <h2 id=access><span class=secno>4. </span><a
   id=access->Obtaining Access to VHS Interfaces Available to the User Agent</a></h2>
   <dl>
     <dt> <b>IDL Definition</b>
   	 <div class=idl-code>
       <pre class=idl>
		  <span id=NavigatorVHSAccess>
		  partial interface Navigator</span> {
		  <span class="idlMethod">    <span><a>VHSAccess</a></span> <span class="idlMethName"><a href="#getvhsaccess">getVHSAccess</a></span>();</span>
		  };

		  </pre>
      </div>
  </dl>
  </dt>
  </dd>
  <p> <b>Methods</b>
  <dt> <b><dfn id=getvhsaccess>getVHSAccess</dfn></b>
  
  <dd>
      <dl>

       <dd> Obtains an interface to enumerate and request access to VHS devices on the user's system. Returns a VHSAccess if there is a VCR connected to the User Agent, null otherwise. This method is blocking
       and User Agent is required to block any other script execution (such a JS Workers for example).
      </dl>
  <dt> Note : This method does not have a callback for error handling, we expect that querying VHS devices is always a successful operation. After so many years on the market, VCR
  are very stable and robust hardware.</dt>
  
   <h2 id=accessInt><span class=secno>5. </span><a
   id=accessInt->VHSAccess Interface</a></h2>
   <dl>
     <dt> <b>IDL Definition</b>
   	 <div class=idl-code>
       <pre>
		  <span id=VHSAccess>
		  interface VHSAccess</span> {
		  <span class="idlMethod">    <span><a>VHSInput</a></span> <span class="idlMethName"><a href="#getInput">getInput</a></span>(float usb_port);</span>
		  <span class="idlMethod">    <span><a>VHSOutput</a></span> <span class="idlMethName"><a href="#getOutput">getOutput</a></span>(float usb_port);</span>
		  };

		  </pre>
      </div>
  </dl>
  </dt>
  </dd>
  <p> <b>Methods</b>
  <dt> <b><dfn id=getvhsaccess>getInput</dfn></b>
  
  <dd>
      <dl>

       <dd> Obtains an VHSInput which you can manipulate to perform input (or commonly named write) operations on a VCR.
      </dl>
      <dd>
      <i>Property :</i>
      <dl>
       <dt> <code><dfn
        id=usb-port
        title="TransitionEvent::propertyName">usb_port</dfn></code> of
        type <code>float</code>, readonly

       <dd> The USB port number of which the VCR is connected. Passing -1 will perform a search on all USB ports to find the first available VCR.
      </dl>
  </dd>
   <dt> <b><dfn id=getvhsaccess>getOutput</dfn></b>
  
  <dd>
      <dl>

       <dd> Obtains an VHSOutput which you can manipulate to perform output (or commonly named read) operations on a VCR.
      </dl>
      <dd>
      <i>Property :</i>
      <dl>
       <dt> <code><dfn
        id=usb-port
        title="TransitionEvent::propertyName">usb_port</dfn></code> of
        type <code>float</code>, readonly

       <dd> The USB port number of which the VCR is connected. Passing -1 will perform a search on all USB ports to find the first available VCR.
      </dl>
  </dd>
  <p>The user agent must round the input number to the closest integer. If the number is exactly between two integers,
  user agents are free to round to either integer.</p>
  <dt> Note : User is expected to use VHSInput and VHSOutput in concert to control the VCR.</dt>

  <h2 id=VHSInput><span class=secno>6. </span><a
   id=VHSInput->VHSInput Interface</a></h2>
   <dl>
     <dt> <b>IDL Definition</b>
   	 <div class=idl-code>
       <pre>
		  <span id=VHSInput>
		  interface VHSInput</span> {
		  <span class="idlMethod">    <span><a>void</a></span> <span class="idlMethName"><a href="#getInput">rewind</a></span>();</span>
		  <span class="idlMethod">    <span><a>void</a></span> <span class="idlMethName"><a href="#getInput">forward</a></span>(float revolution);</span>
		  <span class="idlMethod">    <span><a>void</a></span> <span class="idlMethName"><a href="#getOutput">pause</a></span>();</span>
		  <span class="idlMethod">    <span><a>void</a></span> <span class="idlMethName"><a href="#getOutput">play</a></span>();</span>
		  <span class="idlMethod">    <span><a>void</a></span> <span class="idlMethName"><a href="#getOutput">eject</a></span>();</span>
		  }
		  </pre>
      </div>
  </dl>
  </dt>
  </dd>
  <p> <b>Methods</b>
  <dt> <b><dfn id=getvhsaccess>rewind</dfn></b>
  
  <dd>
      <dl>

       <dd> Rewind the current tape inside the VCR. VCRs are unable to tell the length of the tape and the current progress. There is
       therefore no information on the current progress of rewinding the tape.</dd>
       <dd> The method throws a "<code>BrokeTheTape</code>" exception if the reader detects a lack of resistance on the rewind motor.</dd>
      </dl>
      <dd>
  </dd>
  
    <dt> <b><dfn id=getvhsaccess>forward</dfn></b>
  
  <dd>
      <dl>

       <dd> Forward the current tape inside the VCR. VCRs are unable to tell the length of the tape and the current progress. There is
       therefore no information on the current progress of forwarding the tape.</dd>
       <dd> The method throws a "<code>BrokeTheTape</code>" exception if the reader detects a lack of resistance on the rewind motor.</dd>
      </dl>

      <i>Property :</i>
      <dl>
       <dt> <code><dfn
        id=revoluation
        title="TransitionEvent::propertyName">revolution</dfn></code> of
        type <code>float</code>, readonly

       <dd>The number of revolution run by the motor.</dd>
      </dl>
  </dd>
  
  
    <dt> <b><dfn id=getvhsaccess>play</dfn></b>
  
  <dd>
      <dl>

       <dd> Launch playback of the current tape inside the VCR.
      </dl>
      <dd>
  </dd>
  
      <dt> <b><dfn id=getvhsaccess>pause</dfn></b>
  
  <dd>
      <dl>

       <dd> Pause the playback of the current tape inside the VCR.
      </dl>
      <dd>
  </dd>
  
 <dt> <b><dfn id=getvhsaccess>eject</dfn></b>
  
  <dd>
      <dl>

       <dd> Eject the current tape inside the VCR. The execution of this method is expected to be around 2-3 seconds,
           user agents should warn the user the browser will become unresponsive.
      </dl>
      <dd>
  </dd>
  
  <dt> Note : rewind(), forward(), pause() and eject() are synchronous methods, the script execution is expected to be blocked.</dt>
  
  
  <h2 id=VHSOutput><span class=secno>7. </span><a
   id=VHSInput->VHSOutput Interface</a></h2>
  <dl>
     <dt> <b>IDL Definition</b>
   	 <div class=idl-code>
       <pre>
		  <span id=VHSOutput>
		  interface VHSOutput</span> {
		  <span class="idlMethod">    <span><a>void</a></span> <span class="idlMethName"><a href="#getOutput">streamToYouTube</a></span>(DOMString login, DOMString password);</span>
		  <span class="idlMethod">    <span><a>void</a></span> <span class="idlMethName"><a href="#getOutput">setVideoOutput</a></span>(HTMLElement* element);</span>
		  <span class="idlMethod">    <span><a>void</a></span> <span class="idlMethName"><a href="#getOutput">setUpscaleVideoOutput</a></span>(DOMString quality);</span>
		  }
		  </pre>
      </div>
  </dl>
  </dt>
  </dd>
  <p> <b>Methods</b>
  <dt> <b><dfn id=getvhsaccess>streamToYouTube</dfn></b>
  
  <dd>
      <dl>

       <dd> Stream the current tape to YouTube. User are expecting to launch the playback previously with <a href="#VHSInput">VHSInput</a> interface.
      </dl>
      <dd>
  </dd>
  
    <i>Property :</i>
      <dl>
       <dt> <code><dfn
        id=usb-port
        title="propertyName">login</dfn></code> of
        type <code>DOMString</code>, readonly

       <dd> The login of the user.
      </dl>
      <dt> <code><dfn
        id=usb-port
        title="propertyName">password</dfn></code> of
        type <code>DOMString</code>, readonly

       <dd> The password of the user.
      </dl>
      <br><br>
      <dt> Note : Two steps authentications are not supported by this level.</dt>
  </dd>
  
    <br><br>
 <dt> <b><dfn id=getvhsaccess>setVideoOutput</dfn></b>
  <dd>
      <dl>

       <dd> Set the video output on the element passed in parameter. The element parameter should be a video tag to be able to render the video.
       If an audio element is passed only the sound of the tape will be played. All other types are ignored for now, future level may support Canvas.
      </dl>
      <dd>
      
    <i>Property :</i>
      <dl>
       <dt> <code><dfn
        id=usb-port
        title="TransitionEvent::propertyName">element</dfn></code> of
        type <code>HTMLElement</code>, readonly

       <dd> The element on which the VHS should be played, video element for both audio and video support, audio element for audio only playback.
      </dl>
  </dd>
   <dt> <b><dfn id=getvhsaccess>setUpscaleVideoOutput</dfn></b>
  <dd>
      <dl>

       <dd> Set how the video should be upscaled, note that native VHS resolution is 333x480.
      </dl>
      <dd>
      
    <i>Property :</i>
      <dl>
       <dt> <code><dfn
        id=usb-port
        title="TransitionEvent::propertyName">quality</dfn></code> of
        type <code>DOMString</code>, readonly
		<br><br>
       <dd> The value of the video output quality. Possible values are :
       <ul>
       <li>480i</li>
       <li>576i</li>
       <li>480p</li>
       <li>576p</li>
       <li>720p</li>
       <li>1080i</li>
       <li>1080p</li>
       <li>2160p</li>
       <li>4320p</li>
       <li>8640p</li>
       </ul>
       
       The final quality is at the discretion of the User Agent and how upscaling is implemented.
      </dl>
  </dd>
  
  <h2 id=Examples><span class=secno>8. </span><a
   id=Examples->Examples</a></h2>
   <i>This section is non-normative.</i>
   <p>This example demonstrates how to write a tape rewinder with the Web VHS API:</p>
  <pre class="example" style="border-color: #E0CB52; border-left-width: .5em; border-left-style: solid; padding: .5em;">
        var vhs = window.navigator.getVHSAccess();

        var vhsInput = null;
        for (i = 0; i < Infinity; ++i) {
            vhsInput = vhs.getInput(i);
            if (vhsInput)
                break;
        }

        if (!vhsInput)
            return;

        try {
            vhsInput.rewind();
            vhsInput.eject();
        } catch(e) {
            if (e instanceof BrokeTheTape) {
                alert("Sorry.").
            }
        }
  </pre>
  <h2 id=acknowledgments><span class=secno>9. </span>Acknowledgments</h2>

  <p>Thanks especially to the feedback from the tape-wg.

  <h2 id=references><span class=secno>10. </span>References</h2>

  <h3 class=no-num id=other-references>Other references</h3>
  <!--begin-informative-->
  <!-- Sorted by label -->

  <dl class=bibliography>
   <dt style="display: none"><!-- keeps the doc valid if the DL is empty -->
    <!---->

    <dt id=VHS-IP>[VHS-OVER-IP]

    <dd><a href="#">VHS Over IP</a>: revolutionary method for transferring multimedia content through packet networking (work in progress).
    </dd>
    <!---->


   <dt id=VHS-GL>[VHS-SHADERS]

   <dd><a href="#">Web VHS Shaders specification</a>: dynamic VHS shaders (work in progress).</dd>
   </dd>
   <!---->

   <dt id=VHS-3D>[VHS-3D]

   <dd><a href="#">Web VHS 3D specification</a>: realistic stereoscopic 3D using red and blue filters (work in progress).
   </dd>
   <!---->

  </dl>
  <!--end-informative-->

</html>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-default-doctype-name:"html"
sgml-minimize-attributes:t
End:
-->