MediaPerceptionPrivate IDL and skeleton.

extensions/common/api/media_perception_private.idl

Index: extensions/common/api/media_perception_private.idl
diff --git a/extensions/common/api/media_perception_private.idl b/extensions/common/api/media_perception_private.idl
new file mode 100644
index 0000000000000000000000000000000000000000..a6bf71d7724a42a2c09c44a7ed40bfaa4e953bec
--- /dev/null
+++ b/extensions/common/api/media_perception_private.idl
@@ -0,0 +1,161 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Private API for receiving real-time media perception information.
+[platforms=("chromeos")]
+namespace mediaPerceptionPrivate {
+  enum Status {
+    // An error occurred.
+    ERROR,
+
+    // Attempt to reach media analytics process failed.
+    TIMEOUT,
+
+    // Media analytics process waiting to be launched.
+    UNINITIALIZED,
+
+    // Analytics process running and media processing pipeline started,
+    // but it is not yet receiving image frames. This is a transitional state
+    // between SUSPENDED and RUNNING for the time it takes to warm up the
+    // media processing pipeline, which can take anywhere from a few seconds
+    // to a minute.
+    // Note: STARTED is the initial reply to SetState RUNNING.
+    STARTED,
+
+    // Analytics process running and media processing pipeling injesting image
+    // frames. At this point, MediaPerception signals should be coming over
+    // D-Bus.
+    RUNNING,
+
+    // Analytics process is running and ready to be set to state RUNNING.
+    // The D-Bus communications are enabled but the media processing pipeline
+    // is suspended.
+    SUSPENDED
+  };
+
+  // The system and configuration state of the analytics process and v4lplugin.
+  dictionary State {
+    Status status;

[tbarzic, 2017/05/10 23:45:53]

add a new line between different properties (here and elsewhere)

[Luke Sorenson, 2017/05/11 16:18:22]

Done.

+    // Optional $(ref:setState) parameter. Specifies the video device the media
+    // analytics process should open.
+    // Can be set only when |status| of the analytics process is currently
+    // set to <code>UNINITIALIZED</code> or <code>SUSPENDED</code> and the
+    // desired status is <code>RUNNING</code>.
+    DOMString? deviceContext;
+  };
+
+  dictionary Point {
+    // The horizontal distance from the top left corner of the image.
+    double? x;
+    // The vertical distance from the top left corner of the image.
+    double? y;
+  };
+
+  dictionary BoundingBox {
+    // Specifies whether the points are normalized to the size of the image.
+    boolean? normalized;
+    // The two points that define the corners of a bounding box.
+    Point? topLeft;
+    Point? bottomRight;
+  };
+
+  enum EntityType {
+    UNSPECIFIED,
+    FACE,
+    PERSON
+  };
+
+  dictionary Entity {
+    // A unique id associated with the detected entity, which can be used to
+    // track the entity over time.
+    long? id;
+
+    EntityType? type;
+
+    // Minimum box which captures entire detected entity.
+    BoundingBox? boundingBox;
+
+    // A value for the quality of this detection.
+    double? confidence;
+  };
+
+  // The set of computer vision metadata for an image frame.
+  dictionary FramePerception {
+    long? frameId;
+
+    long? frameWidthInPx;
+    long? frameHeightInPx;
+    // The timestamp associated with the frame (when its recieved by the
+    // analytics process).
+    double? timestamp;
+
+    // The list of entities detected in this frame.
+    Entity[]? entities;
+  };
+
+  dictionary MediaPerception {
+    // The time the media perception data was emitted by the media processing
+    // pipeline. This value will be greater than the timestamp stored within
+    // the FramePerception dictionary and the difference between them can be
+    // viewed as the processing time for a single frame.
+    double? timestamp;
+    // An array of framePerceptions, often just one.
+    FramePerception[]? framePerceptions;
+  };
+
+  // TODO(lasoren): Change this interface based on the compressed images coming

[tbarzic, 2017/05/10 23:45:53]

I'd remove TODOs from here.

[Luke Sorenson, 2017/05/11 16:18:22]

This comment is on an older patch set. TODO no longer there on current patch
set.

+  // from the media analytics process.
+  dictionary ImageFrame {
+    long? width;
+    long? height;
+
+    // TODO(lasoren): Add compression format marker.
+    // The bytes of the image frame.
+    ArrayBuffer? frame;
+  };
+
+  dictionary PerceptionSample {
+    // The video analytics FramePerception for the associated image frame
+    // data.
+    FramePerception? framePerception;
+    // The image frame data for the associated FramePerception object.
+    ImageFrame? imageFrame;
+  };
+
+  dictionary Diagnostics {
+    // A buffer of image frames and the associated video analytics information
+    // that can be used to diagnose a malfunction.
+    PerceptionSample[]? perceptionSamples;
+  };
+
+  callback StateCallback = void(State state);
+
+  callback DiagnosticsCallback = void(Diagnostics diagnostics);
+
+  interface Functions {
+    // Get the status of the media perception process.
+    // |callback| : The current State of the system.
+    static void getState(StateCallback callback);
+
+    // Set the desired state of the system.
+    // |state| : A dictionary with the desired new state. Settable states are
+    // RUNNING and SUSPENDED.
+    // |callback| : The State of the system after setting it. Can be used to
+    // verify the state was set as desired.
+    static void setState(State state, StateCallback callback);
+
+    // Get a diagnostics buffer out of the video analytics process.
+    // |callback| : Returns a Diagnostics dictionary object.
+    static void getDiagnostics(DiagnosticsCallback callback);
+  };
+
+  interface Events {
+    // Fired when media perception information is received from the media
+    // analytics process.
+    // |mediaPerception| : The dictionary which contains a dump of everything
+    // the analytics process has detected or determined from the incoming media
+    // streams.
+    static void onMediaPerception(MediaPerception mediaPerception);
+  };
+};