chromium/chrome/services/media_gallery_util/public/mojom/media_parser.mojom

// Copyright 2017 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module chrome.mojom;

import "media/mojo/mojom/media_types.mojom";
import "mojo/public/mojom/base/read_only_file.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/values.mojom";
import "sandbox/policy/mojom/sandbox.mojom";

// Contains either encoded video frame in |encoded_data|, or decoded video
// frame in |decoded_frame|.
[EnableIf=is_android]
union VideoFrameData {
  array<uint8> encoded_data;
  media.mojom.VideoFrame? decoded_frame;
};

[EnableIf=is_android]
struct ExtractVideoFrameResult {
  VideoFrameData frame_data;
  media.mojom.VideoDecoderConfig config;
};

interface MediaParser {
  // Extracts metadata from media data with |mime_type|, |total_size| and
  // available from |media_data_source|. If there are images referred to in the
  // metadata, and |get_attached_images| is true, return the images in
  // |attached_images|.
  ParseMediaMetadata(string mime_type,
                     int64 total_size,
                     bool get_attached_images,
                     pending_remote<MediaDataSource> media_data_source)
      => (bool parse_success,
          MediaMetadata metadata,
          array<AttachedImage> attached_images);

  // Extracts one video key frame from |media_data_source|. Returns a null
  // result on failure; on success, the result will contain:
  // - the decoded frame if the decoding can be done in the utility process or
  // - an encoded frame if decoding needs to happen in another process
  [EnableIf=is_android]
  ExtractVideoFrame(string mime_type,
                    uint32 total_size,
                    pending_remote<MediaDataSource> media_data_source)
      => (ExtractVideoFrameResult? result);

  // Validates the passed media file with sanity checks, and file decoding
  // for at most |decode_time| wall clock time. Returns |success| true if
  // |file| appears to be a well-formed media file, false otherwise.
  // Note: it is still not safe to decode the file in the calling process after
  // this check.
  CheckMediaFile(mojo_base.mojom.TimeDelta decode_time,
                 mojo_base.mojom.ReadOnlyFile file)
      => (bool success);

  // Used by tests to validate the right CPU information is set on third-party
  // libraries.
  GetCpuInfo() => (int64 libyuv_cpu_flags, int64 ffmpeg_cpu_flags);
};

[ServiceSandbox=sandbox.mojom.Sandbox.kService]
interface MediaParserFactory {
  // Creates a MediaParser. |libyuv_cpuf_lags| are the flags returned by
  // libyuv::InitCpuFlags() from third-party/libyuv and |libavutil_cpu_flags|
  // the flags returned by av_get_cpu_flags() from FFmpeg. These flags have to
  // be passed in as retrieving them may require file access (to /proc/cpuinfo
  // for instance) and the media parser may be run in a sandboxed process with
  // no such access.
  CreateMediaParser(int64 libyuv_cpu_flags, int64 libavutil_cpu_flags)
      => (pending_remote<MediaParser> media_parser);
};

interface MediaDataSource {
  // ParseMediaMetadata interface used to read data for parsing from the
  // calling process.
  Read(int64 position, int64 length) => (array<uint8> data);
};

struct MediaStreamInfo {
  // Describes format of container or codec of stream, i.e. "mp3", "h264".
  string type;

  // A string->string dictionary of tags for the media stream.
  mojo_base.mojom.DictionaryValue additional_properties;
};

// All data are parsed from user-defined media data. The consumer of this API should filter special
// characters if needed. The encoding of strings may be UTF-8 that ffmpeg library assumes strings to
// be UTF-8 but does not validate the encoding.
struct MediaMetadata {
  string mime_type;

  // Defined for video. In pixels.
  int32 height = -1;
  int32 width = -1;

  // Defined for audio and video. In seconds.
  double duration = -1;

  // Defined for video. In degrees.
  int32 rotation;
  // Defined for audio and video.
  string album;

  string artist;
  string comment;
  string copyright;
  int32 disc = -1;
  string genre;
  string language;
  string title;
  int32 track = -1;

  array<MediaStreamInfo> raw_tags;
};

struct AttachedImage {
  // If ParseMediaMetadata returns attached images, each of the images is
  // returned in an AttachedImage object.
  string type;
  array<uint8> data;
};