Cast: Javascript bindings for cast receiver

chrome/common/extensions/api/cast_streaming_receiver_session.idl

Index: chrome/common/extensions/api/cast_streaming_receiver_session.idl
diff --git a/chrome/common/extensions/api/cast_streaming_receiver_session.idl b/chrome/common/extensions/api/cast_streaming_receiver_session.idl
new file mode 100644
index 0000000000000000000000000000000000000000..005c0323236c3813bff81cddb428b120a9bf728b
--- /dev/null
+++ b/chrome/common/extensions/api/cast_streaming_receiver_session.idl
@@ -0,0 +1,80 @@
+// Copyright 2015 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.
+
+// The <code>chrome.cast.streaming.receiverSession</code> API creates a Cast
+// receiver session and returns a WebMediaStream.

[Alpha Left Google, 2015/02/25 20:37:27]

The term WebMediaStraem is an implementation detail. The client of this JS API
knows only MediaStream.

[hubbe, 2015/02/28 00:17:11]

Rewrote the comment since it's not accurate anymore.

+namespace cast.streaming.receiverSession {
+  // The UDP socket address and port.
+  dictionary IPEndPoint {
+    DOMString address;
+    long port;
+  };
+
+  // Params for audio and video codec.
+  dictionary CodecSpecificParams {
+    DOMString key;
+    DOMString value;
+  };
+
+  // RTP receiver parameters.
+  dictionary RtpReceiverParams {
+    long payloadType;
+
+    // Maximum latency in milliseconds. This parameter controls the logic
+    // of flow control. Implementation can adjust latency adaptively and
+    // tries to keep it under this threshold. A larger value allows smoother
+    // playback at the cost of higher latency.
+    long maxLatency;
+
+    DOMString codecName;
+
+    // Synchronization source identifier.
+    long ssrc;
+
+    long feedbackSsrc;
+
+    long? clockRate;

[miu, 2015/02/26 06:23:34]

Do we want clockRate at all?  For audio, IMO, it makes more sense to
automatically use the platform's "native" output sampling rate (there is code I
can point you to find this easily).  For video, clockRate has to be 90000, and
it really doesn't make sense to allow this to be customized.

[hubbe, 2015/02/28 00:17:11]

I think clockRate should always be 48000 or 90000, so I'm removing this.

+
+    // The number of channels.
+    long? channels;

[miu, 2015/02/26 06:23:34]

ditto (same issue as clockRate)

[hubbe, 2015/02/28 00:17:11]

Hardcoding to 2.

+
+    // 32 bytes hex-encoded AES key.
+    DOMString? aesKey;
+
+    // 32 bytes hex-encoded AES IV (Initialization vector) mask.
+    DOMString? aesIvMask;
+
+    // A list of codec specific params.
+    CodecSpecificParams[] codecSpecificParams;

[Alpha Left Google, 2015/02/25 20:37:27]

Since this is in the receiver there is no codec params: the streams are already
encoded. There might be playback options like error concealment, etc. This
should be in a different name or removed.

[hubbe, 2015/02/28 00:17:11]

Removed.

+  };
+
+  interface Functions {
+    // Creates a Cast receiver session using the provided audio and video track as
+    // source. The tracks must be of type MediaStreamTrack. This will
+    // create two RTP streams and a UDP transport that builds the session.
+    // Either |audioTrack| or |videoTrack| can be null but not both. This
+    // means creating a session with only audio or video. If a given
+    // track is null then the created stream ID will be null.
+    //
+    // |audioParams| : the video stream parameters
+    // |videoParams| : the video stream parameters
+    // |localEndpoint| : Set this to bind() to a local UDP port.

[Alpha Left Google, 2015/02/25 20:37:27]

I'm not sure how these two parameters are used.

It seems this receiver session can operate in two modes:
1. Server mode with a given port number. What if the port is already used? Can
it bind to a random port?
2. Client mode that connects to a sender. How is this possible with cast sender?

[hubbe, 2015/02/28 00:17:11]

It can bind to a random port, but there is currently no way to find out what
that port is...
This API needs an error reporting method, so I probably need to add a callback
I included this mode even though it's not compatible with the current sender to
make it possible to avoid firewall dialogs in some cases.

[Alpha Left Google, 2015/03/03 21:53:45]

If this mode is not compatible with sender and we don't plan to have such mode I
think this should be removed. I would prefer an API with less ambiguity. For
example this API can be called "createAndBind". Then later on when we want to
create a receiver in client mode we'll have a "createAndConnect" method.

[hubbe, 2015/03/03 22:36:16]

Done.

+    // |remoteEndpoint| : Set this to connect() to a remote UDP port.
+    // |height| : Video height

[Alpha Left Google, 2015/02/25 20:37:27]

Shouldn't these come from the video frames? 

[hubbe, 2015/02/28 00:17:11]

I need it construct the media stream.

+    // |width| : Video width
+    // |maxFrameRate| : Max video frame rate.

[Alpha Left Google, 2015/02/25 20:37:27]

This seems unnecessary. Since this is the max value, can just be 60 internally.

[hubbe, 2015/02/28 00:17:11]

60 might be ok, I use it construct the media stream and I'm not sure how it's
used in the media stream framework, so it seems safer to make it changeable.

+    // |mediaStreamURL| : URL of MediaStream to add the audio & video to.
+    // |options| : Optional settings.

[Alpha Left Google, 2015/02/25 20:37:27]

What are these options? Can you put them in RtpReceiverParams instead?

[hubbe, 2015/02/28 00:17:11]

They are transport options, renamed.

+    [nocompile] static void create(

[Alpha Left Google, 2015/02/25 20:37:27]

Should there be a callback when create is done? So user can add the MediaStream
to a <video> tag? Or the MediaStream can be used immediately after this call?

[hubbe, 2015/02/28 00:17:11]

A callback is not needed if everything is successful. The media stream can be
used immediately after (or before) this call and you can always add onTrackAdded
(or whatever it is called) to get a callback when the audio & video tracks are
added.

However, we do need some sort of status callback for when things are not
successful.

+        RtpReceiverParams audioParams,
+        RtpReceiverParams videoParams,
+        IPEndPoint localEndpoint,
+        IPEndPoint remoteEndpoint,
+        long height,
+        long width,
+        double maxFrameRate,
+        DOMString mediaStreamURL,
+        optional object options);
+  };

[Alpha Left Google, 2015/03/03 21:53:45]

Is a destroy method needed? Or the receiver will be torn down if all
MediaStreams are not referenced?

[hubbe, 2015/03/03 22:36:16]

Yes, the receiver goes away with the mediastream.

+};