Mojom updates for Motown.

mojo/services/media/common/interfaces/media_types.mojom

Index: mojo/services/media/common/interfaces/media_types.mojom
diff --git a/mojo/services/media/common/interfaces/media_types.mojom b/mojo/services/media/common/interfaces/media_types.mojom
index f56de8f7686359d0b60ff87dfc990975100d8592..a3a88a113df3ab743a64606dcc9cff9ab66724ad 100644
--- a/mojo/services/media/common/interfaces/media_types.mojom
+++ b/mojo/services/media/common/interfaces/media_types.mojom
@@ -2,59 +2,306 @@
 // 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;
 
+// Specifies the type of media.
+struct MediaType {
+  // Broadly identifies the media type and indicates how the details field is
+  // to be interpreted.
+  MediaTypeScheme scheme;
+
+  // Scheme-dependent details.
+  MediaTypeDetails? details;
+};
+
+// Specifies a set of types of media.
+struct MediaTypeSet {
+  // Broadly identifies the media types and indicates how the details field is
+  // to be interpreted.
+  MediaTypeScheme scheme;
+
+  // Scheme-dependent details.
+  MediaTypeSetDetails? details;
+};
+
+// Media type schemes. A media type scheme broadly identifies a media type and
+// indicates what structure, if any, is used to specify the details of the type.
+// If a scheme XYZ has details, then there should be structure definitions for
+// XyzMediaTypeDetails and XyzMediaTypeSetDetails, and fields of those types
+// should appear in MediaTypeDetails and MediaTypeSetDetails respectively.
+enum MediaTypeScheme {
+  // Placeholder indicating type is unknown.
+  UNKNOWN,
+
+  // Placeholder indicating no type.
+  NONE,
+
+  // Placeholder indicating any elementary type.
+  ANY_ELEMENTARY,
+
+  // Placeholder indicating any audio type.
+  ANY_AUDIO,
+
+  // Placeholder indicating any video type.
+  ANY_VIDEO,
+
+  // Placeholder indicating any subpicture type.
+  ANY_SUBPICTURE,
+
+  // Placeholder indicating any text type.
+  ANY_TEXT,
+
+  // Placeholder indicating any multiplexed type.
+  ANY_MULTIPLEXED,
+
+  // Placeholder indicating any type.
+  ANY,
+
+  // Indicates a multiplexed type. See MultiplexedMediaTypeDetails and
+  // MultiplexedMediaTypeSetDetails.
+  MULTIPLEXED,
+
+  // Indicates LPCM audio. See LpcmMediaTypeDetails and LpcmMediaTypeSetDetails.
+  LPCM,
+
+  // Indicates compressed audio. See CompressedAudioMediaTypeDetails and
+  // CompressedAudioMediaTypeSetDetails.
+  COMPRESSED_AUDIO,
+
+  // Indicates video. See VideoMediaTypeDetails and VideoMediaTypeSetDetails.
+  // TODO(dalesat): One scheme for video won't be adequate.
+  VIDEO
+};
+
+// A union of all media type details.
+union MediaTypeDetails {
+  // Each field name should correspond to a value in MediaTypeScheme.
+  MultiplexedMediaTypeDetails multiplexed;
+  LpcmMediaTypeDetails lpcm;
+  CompressedAudioMediaTypeDetails compressed_audio;
+  VideoMediaTypeDetails video;
+};
+
+// A union of all media type set details.
+union MediaTypeSetDetails {
+  // Each field name should correspond to a value in MediaTypeScheme.
+  MultiplexedMediaTypeSetDetails multiplexed;
+  LpcmMediaTypeSetDetails lpcm;
+  CompressedAudioMediaTypeSetDetails compressed_audio;
+  VideoMediaTypeSetDetails video;
+};
+
+// Used to express what boolean values are allowed.
+enum BoolRange {
+  FALSE,
+  TRUE,
+  EITHER
+};
+
+// MediaType details for the LPCM scheme.
+//
+// LPCM packets containing interleaved samples are laid out in the typical
+// manner. The packet contains an integral number of complete frames in
+// presentation order with no padding. Each frame consists of a sample for
+// each channel in order with no padding. Packet duration indicates the number
+// of frames, and packet size is duration * sample_size * channels.
+//
+// LPCM packets containing non-interleaved samples are divided evenly into a
+// region for each channel in order. That is, the starting offset for a given
+// channel is (packet_size / channels) * zero_based_channel_index. Each region
+// contains the same number of samples (given by the duration of the packet)
+// with no padding between samples. Extra space at the end of each region is
+// zero-filled.
+struct LpcmMediaTypeDetails {
+  LpcmSampleFormat sample_format;
+  bool interleaved;
+  uint8 channels;
+  uint32 frames_per_second;
+  // TODO(dalesat): Channel designations.
+};
+
+// MediaTypeSet details for the LPCM scheme.
+struct LpcmMediaTypeSetDetails {
+  LpcmSampleFormat sample_format;
+  BoolRange interleaved;
+  uint8 min_channels;
+  uint8 max_channels;
+  uint32 min_frames_per_second;
+  uint32 max_frames_per_second;
+};
+
+// Sample formats for LPCM media types.
 enum LpcmSampleFormat {
+  // Placeholder indicating sample format is unknown.
+  UNKNOWN,
+
+  // Placeholder indicating any sample format.
+  ANY,
+
+  // 8-bit unsigned samples, sample size 1 byte.
   UNSIGNED_8,
+
+  // 16-bit signed samples, host-endian, sample size 2 bytes.
   SIGNED_16,
-  SIGNED_24_IN_32,  // TODO(johngro): describe the packing for this
+
+  // SIGNED_16 with specific endian-ness. Samples are generally converted to
+  // host-endian order early (in the decoder). Transforms other than decoders
+  // are not required to support these formats.
+  SIGNED_16_LITTLE_ENDIAN,
+  SIGNED_16_BIG_ENDIAN,
+
+  // 24-bit signed samples in 32 bits, host-endian, sample size 4 bytes.
+  // TODO(johngro): describe the packing for this
+  SIGNED_24_IN_32, // Host endian
+
+  // SIGNED_24_IN_32 with specific endian-ness. Samples are generally converted
+  // to host-endian order early (in the decoder). Transforms other than decoders
+  // are not required to support these formats.
+  SIGNED_24_IN_32_LITTLE_ENDIAN,
+  SIGNED_24_IN_32_BIG_ENDIAN,
+
+  // 32-bit floating-point samples, sample size 4 bytes.
+  FLOAT
 };
 
-struct LpcmMediaTypeDetails {
+// Media type details for the Multiplexed scheme.
+struct MultiplexedMediaTypeDetails {
+  // Describes how the streams are multiplexed.
+  MediaType multiplex_type;
+
+  // Media type for each substream.
+  array<MediaType> substream_types;
+};
+
+// Media type set details for the Multiplexed scheme.
+struct MultiplexedMediaTypeSetDetails {
+  // Describes how the streams can be multiplexed.
+  MediaTypeSet multiplex_type_set;
+
+  // Possible substream types.
+  array<MediaTypeSet> substream_type_sets;
+};
+
+// Audio encodings.
+// TODO(dalesat): Add more audio encodings.
+enum AudioEncoding {
+  // Placeholder indicating audio encoding is unknown.
+  UNKNOWN,
+
+  // Placeholder indicating any audio encoding.
+  ANY,
+
+  VORBIS
+};
+
+// Media type details for the COMPRESSED_AUDIO scheme.
+struct CompressedAudioMediaTypeDetails {
+  AudioEncoding encoding;
   LpcmSampleFormat sample_format;
-  uint8 samples_per_frame;
+  bool interleaved;
+  uint8 channels;
   uint32 frames_per_second;
+
+  // Encoding-specific parameter provided by demuxes and used by decoders.
+  string extra_data_base64;
 };
 
-struct LpcmMediaTypeSetDetails {
+// Media type set details for the COMPRESSED_AUDIO scheme.
+struct CompressedAudioMediaTypeSetDetails {
+  AudioEncoding encoding;
   LpcmSampleFormat sample_format;
-  uint8 min_samples_per_frame;
-  uint8 max_samples_per_frame;
+  BoolRange interleaved;
+  uint8 min_channels;
+  uint8 max_channels;
   uint32 min_frames_per_second;
   uint32 max_frames_per_second;
 };
 
-enum MediaTypeScheme {
-  LPCM,
-  // There will be more.
+// Media type details for the VIDEO scheme.
+// TODO(dalesat): Expand and document.
+struct VideoMediaTypeDetails {
+  VideoEncoding encoding;
+  VideoProfile profile;
+  PixelFormat pixel_format;
+  ColorSpace color_space;
+  uint32 width;
+  uint32 height;
+  uint32 coded_width;
+  uint32 coded_height;
+
+  // Encoding-specific parameter provided by demuxes and used by decoders.
+  string extra_data_base64;
 };
 
-union MediaTypeDetails {
-  LpcmMediaTypeDetails lpcm;
-  // There will be more.
+// Media type set details for the VIDEO scheme.
+// TODO(dalesat): Expand and document.
+struct VideoMediaTypeSetDetails {
+  VideoEncoding encoding;
+  uint32 min_width;
+  uint32 max_width;
+  uint32 min_height;
+  uint32 max_height;
 };
 
-struct MediaType {
-  // Broadly identifies the media type and indicates how the details
-  // field is to be interpreted.
-  MediaTypeScheme scheme;
+// Video encodings.
+// TODO(dalesat): Add more video encodings.
+enum VideoEncoding {
+  // Placeholder indicating video encoding is unknown.
+  UNKNOWN,
 
-  // Scheme-dependent details.
-  MediaTypeDetails details;
+  // Placeholder indicating any video encoding.
+  ANY,
+
+  THEORA,
+  VP8
 };
 
-// A union of all media type set details.
-union MediaTypeSetDetails {
-  // Each field name should correspond to a value in MediaTypeScheme.
-  LpcmMediaTypeSetDetails lpcm;
+// Video profiles.
+// TODO(dalesat): Blindly copied from Chromium, revisit.
+enum VideoProfile {
+  UNKNOWN,
+  NOT_APPLICABLE,
+  H264_BASELINE,
+  H264_MAIN,
+  H264_EXTENDED,
+  H264_HIGH,
+  H264_HIGH10,
+  H264_HIGH422,
+  H264_HIGH444_PREDICTIVE,
+  H264_SCALABLE_BASELINE,
+  H264_SCALABLE_HIGH,
+  H264_STEREO_HIGH,
+  H264_MULTIVIEW_HIGH

[johngro, 2015/12/10 21:46:03]

Codec-type descriptions in metadata is a very tricky subject.  I'm certain that
we will revisit this later, but I'm not sure that we want to go down the route
of a centrally defined enum in the long run.  In particular, putting specific
sub-types of codecs (a-la all of the profiles of H264 listed here) becomes a
real pain when it comes to negotiation and maintenance.  Decentralized magic
number systems (like GUIDs) are unappealing for other reasons.  Mime-types are
very flexible and easily allow for third party extensions, but have their own
problems (usually very poorly document and almost always misused).

TL;DR, this problem is really nasty.  The enumeration of all the H264 types is
what set me off.  No action requested, but let's talk about what we want to do
long term in the near future.

[dalesat, 2015/12/10 22:33:38]

Acknowledged.

 };
 
-// Specifies a set of types of media.
-struct MediaTypeSet {
-  // Broadly identifies the media types and indicates how the details
-  // field is to be interpreted.
-  MediaTypeScheme scheme;
+// Pixel format.
+// TODO(dalesat): Blindly copied from Chromium, revisit.

[johngro, 2015/12/10 21:46:03]

agreed about revisiting this.  I really don't want to end up with having enums
for descriptions of every pixel packing format under the sun.  Generalized
descriptions have their own problems.  Easy to describe everything, difficult to
write code which can understand the descriptions and produce efficient
implementations of handling.  Also difficult to provide an accurate description
of what you can and cannot handle.  I opined on this at length in the VideoPipe
document I wrote and sent out a couple of months ago.

[dalesat, 2015/12/10 22:33:38]

Acknowledged.

+enum PixelFormat {
+  UNKNOWN,
+  I420,  // 12bpp YUV planar 1x1 Y, 2x2 UV samples, a.k.a. YU12.
+  YV12,  // 12bpp YVU planar 1x1 Y, 2x2 VU samples.
+  YV16,  // 16bpp YVU planar 1x1 Y, 2x1 VU samples.
+  YV12A,  // 20bpp YUVA planar 1x1 Y, 2x2 VU, 1x1 A samples.
+  YV24,  // 24bpp YUV planar, no subsampling.
+  NV12,  // 12bpp with Y plane followed by a 2x2 interleaved UV plane.
+  NV21,  // 12bpp with Y plane followed by a 2x2 interleaved VU plane.
+  UYVY,  // 16bpp interleaved 2x1 U, 1x1 Y, 2x1 V, 1x1 Y samples.
+  YUY2,  // 16bpp interleaved 1x1 Y, 2x1 U, 1x1 Y, 2x1 V samples.
+  ARGB,  // 32bpp ARGB, 1 plane.
+  XRGB,  // 24bpp XRGB, 1 plane.
+  RGB24,  // 24bpp BGR, 1 plane.
+  RGB32,  // 32bpp BGRA, 1 plane.
+  MJPEG,  // MJPEG compressed.
+  MT21
+};
 
-  // Scheme-dependent details.
-  MediaTypeSetDetails details;
+// Pixel format.
+// TODO(dalesat): Blindly copied from Chromium, revisit.
+enum ColorSpace {
+  UNKNOWN,
+  NOT_APPLICABLE,
+  JPEG,
+  HD_REC709,
+  SD_REC601
 };