Add an initial revision of an audio server.

mojo/services/media/audio/interfaces/audio_track.mojom

Index: mojo/services/media/audio/interfaces/audio_track.mojom
diff --git a/mojo/services/media/audio/interfaces/audio_track.mojom b/mojo/services/media/audio/interfaces/audio_track.mojom
new file mode 100644
index 0000000000000000000000000000000000000000..29cb218d3f37133cb0478e0a116518f04cdef526
--- /dev/null
+++ b/mojo/services/media/audio/interfaces/audio_track.mojom
@@ -0,0 +1,89 @@
+// 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.
+
+module mojo.media;
+
+import "mojo/services/media/common/interfaces/media_common.mojom";
+import "mojo/services/media/common/interfaces/media_pipe.mojom";
+import "mojo/services/media/common/interfaces/media_types.mojom";
+import "mojo/services/media/common/interfaces/rate_control.mojom";
+
+struct AudioTrackDescriptor {
+  // The track supports the union of all these media type sets.
+  array<MediaTypeSet> supported_media_types;
+
+  // Whether the track supports a push transport.
+  bool supports_push_transport;
+
+  // Whether the track supports a pull transport.
+  bool supports_pull_transport;

[jeffbrown, 2015/11/04 23:43:32]

I thought we were only going to support push?

[johngro, 2015/11/06 02:20:23]

copied directly from Dale's design doc.  Let's bring this up when we get
together to talk about overall MediaPipe design stuff.  I'll leave a comment
here and add the topic to my design todo list.

[dalesat, 2015/11/06 06:14:11]

Push-only came up in the doc review...no longer there.

[johngro, 2015/11/06 20:24:25]

Acknowledged.

What do you think I should do here?  Keep these fields, kill them, or keep the
comment and discuss later?

[dalesat, 2015/11/06 21:03:56]

If you're not using them, you might as well delete them.

[johngro, 2015/11/09 20:25:16]

Done.

+};
+
+struct AudioTrackConfiguration {
+  // The media type to use.
+  MediaType media_type;
+
+  // Desired maximum buffer size, in frames of audio.
+  uint64 max_frames;
+
+  // Ratio of audio frames to media time ticks.
+  // 
+  // Presentation time stamps on audio packets are expressed in units of media
+  // time ticks.  Many users will choose to use units of audio frames to express
+  // their media time, and can simply leave this ratio at the default of 1:1.
+  // For some, however, it may be more convenient to use different units for
+  // media time.  For example, if the audio frame rate was 48KHz, and the time
+  // stamps are expressed in 90KHz units (the units used by MPEG-2 Program
+  // Stream timestamps), the ratio should be set to 48000:90000 (aka, 8:15).
+  // IOW - audio_frame_ratio would be set to 8 and media_time_ratio would be set
+  // to 15.
+  //
+  // Neither of these values may be 0.  A configuration error will occur if they
+  // are.
+  uint32 audio_frame_ratio = 1;
+  uint32 media_time_ratio  = 1;
+};
+
+interface AudioTrack {
+  // Get the descriptor.
+  Describe() => (AudioTrackDescriptor descriptor);
+
+  // Set the configuration, receive a pipe to send data to in return.
+  // Possible results include...
+  //
+  // kOK:
+  //   Configuration successful, the bound pipe interface is ready to be used.
+  // 
+  // kInvalidArgs:

[jeffbrown, 2015/11/04 23:43:32]

close the connection

[johngro, 2015/11/06 02:20:24]

Acknowledged.

FWIW - I'm putting these all in my close the post V0 close-the-connection
bucket.  From here on out, I'll be acking these comments, and adding them to my
list of cleanup tasks, but I'm not going to change them in this CL.  Once this
is in, I'll file a bug and get to work cleaning this up.

+  //   One or more of the configuration arguments are illegal.  For example, a
+  //   value of 0 for either numerator or denominator of the audio frame to
+  //   media time ratio.
+  //
+  // kUnsupportedConfig:

[jeffbrown, 2015/11/04 23:43:32]

if the client was able to determine this ahead of time (by looking at the
descriptor) then we can treat this as invalid arguments and close the connection

[johngro, 2015/11/06 02:20:24]

Acknowledged.

+  //   The requested configuration is not supported by this track.
+  //
+  // kInsufficientResources:
+  //   Resource limitations prevent configuring the audio track is the desired
+  //   way.  Perhaps there is not enough RAM to support the 2.7 days of audio
+  //   buffer you requested, or perhaps there is not enough CPU power given the
+  //   existing active tracks in the system to support rendering 128 channels
+  //   at 1.5 MHz frame rate.
+  //
+  // kBadState:

[jeffbrown, 2015/11/04 23:43:32]

This suggests coupling the creation of an audio track with its configuration.  I
think it might also be reasonable to say that an audio track can never be
reconfigured.  If you need a new configuration you can just create a new audio
track.  Audio tracks are fungible.

[johngro, 2015/11/06 02:20:24]

Acknowledged.

Agreed, I do not think we currently have a plans to reconfigure audio pipes on
the fly.  Per our face to face discussion, you currently need to have a track
interface in order to query the server's track capabilities.  I'm going to add
this to the design discussion list, but assuming that we all agree, I will come
back later and hoist track capability enumeration up to the server interface
level, and make configuration part of CreateTrack (eliminating this method in
the process).

+  //  The track is already configured and has pending data in its pipe.  Data
+  //  needs to be flushed and the media clock must be stopped before the track
+  //  may be re-configured.
+  Configure(AudioTrackConfiguration configuration,
+            MediaPipe& pipe) => (MediaResult result);
+
+  // Request the rate control interface for this AudioTrack
+  // Possbile results include...
+  //
+  // kOK:
+  //  Everything went well.
+  //
+  // kBadState:
+  //  Rate control interface is already bound to a different client.
+  GetRateControl(RateControl& rate_control) => (MediaResult result);

[jeffbrown, 2015/11/04 23:43:32]

I can't think of a meaningful error to report here.

Note that it's not possible for one end of message pipe to be bound the same
thing twice because it is only ever moved and never duplicated.

[johngro, 2015/11/06 02:20:24]

It is possible for anyone with access to the AudioTrack interface instance to
create a new interface request (which gives them a new unbound message pipe
endpoint) and call this method again.  The rate control interface facet exposed
by audio tracks currently supports only 1-to-1 relationships, not one to many,
so it will refuse to bind to a second message pipe (if asked to do so) and
return BadState in response.

In theory, there might be some merit in supporting a 1-to-many for the rate
control interface, but I cannot come up with a practical use case yet, so it is
limited to 1-1 for the moment.

I'm going to lump this into the close-connection bucket.

+};