// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.media;

// fuchsia.media contains definitions shared by the various fuchsia.media.*
// libraries. Definitions in this file concern the representation of type
// (i.e. format or encoding) for elementary streams.

using fuchsia.images;

/// Describes the type of an elementary stream.
struct StreamType {
    /// Medium-specific type information.
    MediumSpecificStreamType medium_specific;

    /// Encoding (see constants below). This value is represented as a string
    /// so that new encodings can be introduced without modifying this file.
    string:255 encoding;

    /// Encoding-specific parameters, sometimes referred to as 'out-of-band
    /// data'. Typically, this data is associated with a compressed stream and
    /// provides parameters required to decompress the stream. This data is
    /// generally opaque to all parties except the producer and consumer of the
    /// stream.
    vector<uint8>? encoding_parameters;
};

/// A union of all medium-specific stream type structs.
union MediumSpecificStreamType {
    1: AudioStreamType audio;
    2: VideoStreamType video;
    3: TextStreamType text;
    4: SubpictureStreamType subpicture;
};

/// Audio encodings.
const string AUDIO_ENCODING_AAC = "fuchsia.media.aac";
const string AUDIO_ENCODING_AACLATM = "fuchsia.media.aaclatm";
const string AUDIO_ENCODING_AMRNB = "fuchsia.media.amrnb";
const string AUDIO_ENCODING_AMRWB = "fuchsia.media.amrwb";
const string AUDIO_ENCODING_APTX = "fuchsia.media.aptx";
const string AUDIO_ENCODING_FLAC = "fuchsia.media.flac";
const string AUDIO_ENCODING_GSMMS = "fuchsia.media.gsmms";
const string AUDIO_ENCODING_LPCM = "fuchsia.media.lpcm";
const string AUDIO_ENCODING_MP3 = "fuchsia.media.mp3";
const string AUDIO_ENCODING_PCMALAW = "fuchsia.media.pcmalaw";
const string AUDIO_ENCODING_PCMMULAW = "fuchsia.media.pcmmulaw";
const string AUDIO_ENCODING_SBC = "fuchsia.media.sbc";
const string AUDIO_ENCODING_VORBIS = "fuchsia.media.vorbis";
const string AUDIO_ENCODING_OPUS = "fuchsia.media.opus";

/// Video encodings.
const string VIDEO_ENCODING_H263 = "fuchsia.media.h263";
const string VIDEO_ENCODING_H264 = "fuchsia.media.h264";
const string VIDEO_ENCODING_MPEG4 = "fuchsia.media.mpeg4";
const string VIDEO_ENCODING_THEORA = "fuchsia.media.theora";
const string VIDEO_ENCODING_UNCOMPRESSED = "fuchsia.media.uncompressed_video";
const string VIDEO_ENCODING_VP3 = "fuchsia.media.vp3";
const string VIDEO_ENCODING_VP8 = "fuchsia.media.vp8";
const string VIDEO_ENCODING_VP9 = "fuchsia.media.vp9";

/// Describes the compression applied to a stream. This type can be used in conjunction with
/// `AudioStreamType` or `VideoStreamType` to represent a medium-specific compressed type.
struct Compression {
    /// The type of compression applied to the stream. This is generally one of the *_ENCODING_*
    /// values, though `AUDIO_ENCODING_LPCM` and `VIDEO_ENCODING_UNCOMPRESSED` must not be used,
    /// because those encodings are regarded as uncompressed.
    CompressionType type;

    /// Type-specific, opaque 'out-of-band' parameters describing the compression of the stream.
    bytes:8192? parameters;
};

/// An identifier for compression types.
alias CompressionType = string:256;

// /////////////////////////////////////////////////////////////////////////////
// Audio

/// Describes the type of an audio elementary stream.
struct AudioStreamType {
    AudioSampleFormat sample_format;
    uint32 channels;
    uint32 frames_per_second;
    // TODO(mpuryear): Add channel config.
};

/// Enumerates the supported audio sample formats.
enum AudioSampleFormat {
    /// 8-bit unsigned samples, sample size 1 byte.
    UNSIGNED_8 = 1;

    /// 16-bit signed samples, host-endian, sample size 2 bytes.
    SIGNED_16 = 2;

    /// 24-bit signed samples in 32 bits, host-endian, sample size 4 bytes.
    SIGNED_24_IN_32 = 3;

    /// 32-bit floating-point samples, sample size 4 bytes.
    FLOAT = 4;
};

// /////////////////////////////////////////////////////////////////////////////
// Video

/// Describes the type of a video elementary stream.
struct VideoStreamType {
    fuchsia.images.PixelFormat pixel_format;
    // TODO(dalesat): Use fuchsia.images.ColorSpace.
    ColorSpace color_space;

    /// Dimensions of the video frames as displayed in pixels.
    uint32 width;
    uint32 height;

    /// Dimensions of the video frames as encoded in pixels. These values must
    /// be equal to or greater than the respective width/height values.
    uint32 coded_width;
    uint32 coded_height;

    /// The aspect ratio of a single pixel as frames are intended to be
    /// displayed.
    uint32 pixel_aspect_ratio_width;
    uint32 pixel_aspect_ratio_height;

    /// The number of bytes per 'coded' row in the primary video plane.
    uint32 stride;
};

// TODO(dalesat): Replace with fuchsia.images.ColorSpace.
enum ColorSpace {
    UNKNOWN = 0;
    NOT_APPLICABLE = 1;
    JPEG = 2;
    HD_REC709 = 3;
    SD_REC601 = 4;
};

// /////////////////////////////////////////////////////////////////////////////
// Text

/// Describes the type of a text elementary stream.
struct TextStreamType {
    // TODO(dalesat): Define.
};

// /////////////////////////////////////////////////////////////////////////////
// Subpicture

/// Describes the type of a subpicture elementary stream.
struct SubpictureStreamType {
    // TODO(dalesat): Define.
};