1// Copyright 2013 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// The <code>chrome.cast.streaming.rtpStream</code> API allows configuration
6// of encoding parameters and RTP parameters used in a Cast streaming
7// session.
8//
9// Valid stream IDs are positive and non-zero.
10namespace cast.streaming.rtpStream {
11  // Params for audio and video codec.
12  dictionary CodecSpecificParams {
13    DOMString key;
14    DOMString value;
15  };
16
17  // RTP payload param.
18  dictionary RtpPayloadParams {
19    long payloadType;
20
21    // Maximum latency in milliseconds. This parameter controls the logic
22    // of flow control. Implementation can adjust latency adaptively and
23    // tries to keep it under this threshold. A larger value allows smoother
24    // playback at the cost of higher latency.
25    long maxLatency;
26
27    // Minimum latency in milliseconds. Defaults to |maxLatency|.
28    long? minLatency;
29
30    // Starting latency for animated content in milliseconds.
31    // Defaults to |maxLatency|.
32    long? animatedLatency;
33
34    DOMString codecName;
35
36    // Synchronization source identifier.
37    long ssrc;
38
39    long feedbackSsrc;
40
41    long? clockRate;
42
43    // Minimum bitrate in kilobits per second.
44    long? minBitrate;
45
46    // Maximum bitrate in kilobits per second.
47    long? maxBitrate;
48
49    // The number of channels.
50    long? channels;
51
52    // The maximum frame rate.
53    double? maxFrameRate;
54
55    // 32 bytes hex-encoded AES key.
56    DOMString? aesKey;
57
58    // 32 bytes hex-encoded AES IV (Initialization vector) mask.
59    DOMString? aesIvMask;
60
61    // A list of codec specific params.
62    CodecSpecificParams[] codecSpecificParams;
63  };
64
65  // Cast RTP parameters.
66  dictionary RtpParams {
67    // RTP payload params.
68    RtpPayloadParams payload;
69
70    DOMString[] rtcpFeatures;
71  };
72
73  // Callback from the <code>create</code> method.
74  // |id| : The ID for the RTP stream.
75  callback CreateCallback = void (long streamId);
76
77  // Callback from the <code>getRawEvents</code> method.
78  // |rawEvents|: compressed serialized raw bytes containing raw events
79  //              recorded for a stream.
80  // The compression is in gzip format.
81  // The serialization format can be found at
82  // media/cast/logging/log_serializer.cc.
83  callback GetRawEventsCallback = void (ArrayBuffer rawEvents);
84
85  // Callback from the <code>getStats</code> method.
86  // |rawEvents|: dictionary object containing stats recorded for a stream.
87  // The format can be found at
88  // media/cast/logging/stats_event_subscriber.cc.
89  callback GetStatsCallback = void (object stats);
90
91  interface Functions {
92    // Destroys a Cast RTP stream.
93    // |streamId| : The RTP stream ID.
94    [nocompile] static void destroy(long streamId);
95
96    // Returns an array of supported parameters with default values.
97    // This includes a list of supported codecs on this platform and
98    // corresponding encoding and RTP parameters.
99    // |streamId| : The RTP stream ID.
100    [nocompile] static RtpParams[] getSupportedParams(long streamId);
101
102    // Activates the RTP stream by providing the parameters.
103    // |streamId| : The RTP stream ID.
104    // |params| : Parameters set for this stream.
105    [nocompile] static void start(long streamId, RtpParams params);
106
107    // Stops activity on the specified stream.
108    // |streamId| : The RTP stream ID.
109    [nocompile] static void stop(long streamId);
110
111    // Enables / disables logging for a stream.
112    // |enable|: If true, enables logging. Otherwise disables logging.
113    [nocompile] static void toggleLogging(long streamId, boolean enable);
114
115    // Get raw events for a stream in the current session.
116    // |streamId|: Stream to get events for.
117    // |extraData|: Extra data to attach to the log, e.g. system info or
118    //              experiment tags, in key-value JSON string format.
119    // |callback|: Called with the raw events.
120    [nocompile] static void getRawEvents(
121        long streamId, optional DOMString extraData,
122        GetRawEventsCallback callback);
123
124    // Get stats for a stream in the current session.
125    // |streamId|: Stream to get stats for.
126    // |callback|: Called with the stats.
127    [nocompile] static void getStats(
128        long streamId, GetStatsCallback callback);
129  };
130
131  interface Events {
132    // Event fired when a Cast RTP stream has started.
133    // |streamId| : The ID of the RTP stream.
134    static void onStarted(long streamId);
135
136    // Event fired when a Cast RTP stream has stopped.
137    // |streamId| : The ID of the RTP stream.
138    static void onStopped(long streamId);
139
140    // Event fired when a Cast RTP stream has error.
141    // |streamId| : The ID of the RTP stream.
142    // |errorString| : The error info.
143    static void onError(long streamId, DOMString errorString);
144  };
145};
146