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

// 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.

[DartPackage="mojo_services"]
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;
};

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...
  //
  // OK:
  //   Configuration successful, the bound pipe interface is ready to be used.
  //
  // INVALID_ARGUMENT:
  //   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:
  //   The requested configuration is not supported by this track.
  //
  // INSUFFICIENT_RESOURCES:
  //   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.
  //
  // BAD_STATE:
  //  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...
  //
  // OK:
  //  Everything went well.
  //
  // BAD_STATE:
  //  Rate control interface is already bound to a different client.
  GetRateControl(RateControl& rate_control) => (MediaResult result);
};