chrome/common/extensions/api/audio_modem.idl

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.audio_modem</code> API
   6 // to transmit and receive short tokens over audio.
   7 namespace audioModem {
   8   // The audio bands supported.
   9   enum Audioband {
  10     // Audible (up to 3 kHz)
  11     audible,
  12     // Inaudible (18-20 kHz)
  13     inaudible
  14   };
  15
  16   // Details for how a token is encoded in audio.
  17   dictionary TokenEncoding {
  18     // The length of the tokens to transmit, in bytes.
  19     // For now, apps must always use the same token length.
  20     long tokenLength;
  21     // Whether to use a 2-byte CRC checksum. Defaults to false.
  22     boolean? crc;
  23     // Whether to use a parity symbol. Defaults to false.
  24     boolean? parity;
  25   };
  26
  27   // Details of a transmit or receive request.
  28   dictionary RequestParams {
  29     // How long to transmit or receive for.
  30     // The timeout has a maximum of 10 minutes for transmit,
  31     // or 1 hour for receive.
  32     long timeoutMillis;
  33     // The audio band to use.
  34     Audioband band;
  35     // The token encoding details.
  36     TokenEncoding encoding;
  37   };
  38
  39   // Results of token decoding.
  40   dictionary ReceivedToken {
  41     // The token contents in raw bytes.
  42     ArrayBuffer token;
  43     // The audio band the token was heard on.
  44     Audioband band;
  45   };
  46
  47   // The result of a requested operation.
  48   enum Status {
  49     // The requested operation was processed successfully.
  50     success,
  51     // The request was invalid. See chrome.runtime.lastError for details.
  52     invalidRequest,
  53     // The requested audio band is already in use by another client.
  54     // Eventually, simultaneous tokens will be time-sliced,
  55     // and this error will no longer occur.
  56     inUse,
  57     // Audio encoding or decoding failed.
  58     coderError
  59   };
  60
  61   // A callback to report the status of a request.
  62   callback StatusCallback = void(Status status);
  63
  64   interface Functions {
  65     // Transmit a token. Only one can be transmitted at a time.
  66     // Transmission of any previous tokens (by this app) will stop.
  67     static void transmit(
  68         RequestParams params, ArrayBuffer token, StatusCallback callback);
  69     // Stop any active transmission on the specified band.
  70     static void stopTransmit(Audioband band, StatusCallback callback);
  71     // Start listening for audio tokens. For now,
  72     // only one app will be able to listen at a time.
  73     static void receive(RequestParams params, StatusCallback callback);
  74     // Stop any active listening on the specified band.
  75     static void stopReceive(Audioband band, StatusCallback callback);
  76   };
  77
  78   interface Events {
  79     // Audio tokens have been received.
  80     static void onReceived(ReceivedToken[] tokens);
  81     // Transmit could not be confirmed.
  82     // The speaker volume might be too low.
  83     static void onTransmitFail(Audioband band);
  84   };
  85 };
  86