[PPAPI] API definition for audio media stream artifacts

ppapi/api/ppb_media_stream_audio_track.idl

 /* Copyright 2014 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.
  */
 
 /**
- * Defines the <code>PPB_MediaStreamVideoTrack</code> interface. Used for
- * receiving video frames from a MediaStream video track in the browser.
+ * Defines the <code>PPB_MediaStreamAudioTrack</code> interface. Used for
+ * receiving audio frames from a MediaStream audio track in the browser.
  * This interface is still in development (Dev API status) and may change.
  */
 label Chrome {
   [channel=dev] M34 = 0.1
 };
 
 /**
  */
-interface PPB_MediaStreamVideoTrack {
+interface PPB_MediaStreamAudioTrack {

[dmichael (off chromium), 2014/01/07 22:00:59]

We had a discussion about the names before holiday break, but I don't think I
had a chance to respond, and I'm not sure if we concluded anything. I suspect
you're going to want this to be named something implying it's for input, like:
PPB_MediaStreamAudioInputTrack
or something?

Thoughts? (Sorry for forgetting where we were before)

[Peng, 2014/01/07 22:29:27]

I asked yuzhu, the dev API can be changed. So I landed it. I thought it is
easier to fix and review it in a separate CL. Sorry for it.

When I was implementing the video track, I found it is very easy to combine
producer and consumer to a single Track interface. We just need add a Create()
method to create produce track.

So there are two solutions.
1. Single interface MediaStreamAudioTrack for both input and output
Pro:
 * It saves a lot of code.
 * HTML5 only has MediaStreamTrack object. Single interface is more familiar for
web developers.
Con:
 * Maybe it is a little confusing if the API is not well documented.

2. Two interfaces MediaStreamAudioTrackSource and
MediaStreamAudioTrackDestination.


I am slight prefer solution 1. What do you think?

[dmichael (off chromium), 2014/01/09 17:07:46]

No, that's totally fine. We can come back around and change it still.

 
In this world, would a plugin ever be able to use the same MediaStreamVideoTrack
to read _and_ write tracks? If so we *definitely* should not separate them. If
not, it feels slightly wrong to have them in the same API. Not sure. Maybe
adding a "read only" field later on will help with that confusion.

Another thing we have to think about is the interaction with JavaScript. Since
we want to be able to pass these back and forth using
PPB_Messaging/PPP_Messaging, it might be best to have a 1-1 mapping. So that
would argue for having 1 type for VideoStreamTrack:
http://dev.w3.org/2011/webrtc/editor/getusermedia.html#idl-def-VideoStreamTrack
...and 1 type for AudioStreamTrack...
http://dev.w3.org/2011/webrtc/editor/getusermedia.html#idl-def-AudioStreamTrack

(In fact, I wonder if PPB_AudioStreamTrack and PPB_VideoStreamTrack are better
names, to match the HTML spec?)
I think given that it matches better with HTML/JavaScript, I think I agree with
you. We'll have to keep an eye out for that when you add pushing frames to that
APIs, because the current file-level documentation doesn't reflect that.

[Peng, 2014/01/09 20:59:58]

Right now, I can not image how a plugin side track can be used both for both
read and write. Adding a "read only" field should help a lot.
I agree. JS NaCL 1-1 mapping is better. So AudioStreamTrack and VideoStreamTrack
are better names. I will rename them later before moving them to stable channel.

   /**
-   * Determines if a resource is a MediaStream video track resource.
+   * Determines if a resource is a MediaStream audio track resource.
    *
    * @param[in] resource The <code>PP_Resource</code> to test.
    *
    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
-   * resource is a Mediastream video track resource or <code>PP_FALSE</code>
+   * resource is a Mediastream audio track resource or <code>PP_FALSE</code>
    * otherwise.
    */
-  PP_Bool IsMediaStreamVideoTrack([in] PP_Resource resource);
+  PP_Bool IsMediaStreamAudioTrack([in] PP_Resource resource);
 
   /**
    * Configures underlying frame buffers for incoming frames.
    * If the application doesn't want to drop frames, then the
    * <code>max_buffered_frames</code> should be chosen such that inter-frame
    * processing time variability won't overrun the input buffer. If the buffer
    * is overfilled, then frames will be dropped. The application can detect
    * this by examining the timestamp on returned frames.
    * If <code>Configure()</code> is not used, default settings will be used.
    *
-   * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
+   * @param[in] audio_track A <code>PP_Resource</code> corresponding to an audio
    * resource.
-   * @param[in] max_buffered_frames The maximum number of video frames to
+   * @param[in] samples_per_frame The number of audio samples in an audio frame.
+   * @param[in] max_buffered_frames The maximum number of audio frames to
    * hold in the input buffer.
    *
    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
    */
-  int32_t Configure([in] PP_Resource video_track,
+  int32_t Configure([in] PP_Resource audio_track,
+                    [in] uint32_t samples_per_frame,
                     [in] uint32_t max_buffered_frames);
 
   /**
-   * Returns the track ID of the underlying MediaStream video track.
+   * Returns the track ID of the underlying MediaStream audio track.
    *
-   * @param[in] video_track The <code>PP_Resource</code> to check.
+   * @param[in] audio_track The <code>PP_Resource</code> to check.
    *
    * @return A <code>PP_Var</code> containing the MediaStream track ID as
    * a string.
    */
-  PP_Var GetId([in] PP_Resource video_track);
+  PP_Var GetId([in] PP_Resource audio_track);
 
   /**
    * Checks whether the underlying MediaStream track has ended.
    * Calls to GetFrame while the track has ended are safe to make and will
    * complete, but will fail.
    *
-   * @param[in] video_track The <code>PP_Resource</code> to check.
+   * @param[in] audio_track The <code>PP_Resource</code> to check.
    *
    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
    * MediaStream track has ended or <code>PP_FALSE</code> otherwise.
    */
-  PP_Bool HasEnded([in] PP_Resource video_track);
+  PP_Bool HasEnded([in] PP_Resource audio_track);
 
   /**
-   * Gets the next video frame from the MediaStream track.
+   * Gets the next audio frame from the MediaStream track.
    * If internal processing is slower than the incoming frame rate, new frames
    * will be dropped from the incoming stream. Once the input buffer is full,
    * frames will be dropped until <code>RecycleFrame()</code> is called to free
    * a spot for another frame to be buffered.
    * If there are no frames in the input buffer,
    * <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the
    * <code>callback</code> will be called, when a new frame is received or an
    * error happens.
    *
-   * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
+   * @param[in] audio_track A <code>PP_Resource</code> corresponding to an audio
    * resource.
-   * @param[out] frame A <code>PP_Resource</code> corresponding to a VideoFrame
+   * @param[out] frame A <code>PP_Resource</code> corresponding to an AudioFrame
    * resource.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion of GetFrame().
    *
    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
    * Returns PP_ERROR_NOMEMORY if <code>max_buffered_frames</code> frames buffer
    * was not allocated successfully.
    */
-  int32_t GetFrame([in] PP_Resource video_track,
+  int32_t GetFrame([in] PP_Resource audio_track,
                    [out] PP_Resource frame,
                    [in] PP_CompletionCallback callback);
 
   /**
    * Recycles a frame returned by <code>GetFrame()</code>, so the track can
    * reuse the underlying buffer of this frame. And the frame will become
    * invalid. The caller should release all references it holds to
    * <code>frame</code> and not use it anymore.
    *
-   * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
+   * @param[in] audio_track A <code>PP_Resource</code> corresponding to an audio
    * resource.
-   * @param[in] frame A <code>PP_Resource</code> corresponding to a VideoFrame
+   * @param[in] frame A <code>PP_Resource</code> corresponding to an AudioFrame
    * resource returned by <code>GetFrame()</code>.
    *
    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
    */
-  int32_t RecycleFrame([in] PP_Resource video_track,
+  int32_t RecycleFrame([in] PP_Resource audio_track,
                        [in] PP_Resource frame);
 
   /**
-   * Closes the MediaStream video track and disconnects it from video source.
+   * Closes the MediaStream audio track and disconnects it from audio source.

[dmichael (off chromium), 2014/01/07 22:00:59]

from +the+ audio

[Peng, 2014/01/07 22:29:27]

Done.

    * After calling <code>Close()</code>, no new frames will be received.
    *
-   * @param[in] video_track A <code>PP_Resource</code> corresponding to a
-   * MediaStream video track resource.
+   * @param[in] audio_track A <code>PP_Resource</code> corresponding to a
+   * MediaStream audio track resource.
    */
-  void Close([in] PP_Resource video_track);
+  void Close([in] PP_Resource audio_track);
 };