chromium/src/third_party/blink/renderer/modules/webcodecs/video_decoder.idl

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

// https://github.com/WICG/web-codecs

// A VideoDecoder processes a queue of configure, decode, and flush requests.
// Requests are taken from the queue sequentially but may be processed
// concurrently.
//
// TODO(sandersd): Specify a tune() implementation for changing decoder
// parameters (separate from stream parameters). This is more important for
// encoders.
[
    Exposed=(Window,DedicatedWorker),
    RuntimeEnabled=WebCodecs,
    ActiveScriptWrappable
] interface VideoDecoder {
  // |init| includes an |output| callback for emitting VideoFrames and an
  // |error| callback for emitting decode errors.
  //
  // When in an closed state, all methods will fail.
  //
  // TODO(sandersd): Consider adding a state or last error attribute.
  [CallWith=ScriptState, RaisesException, MeasureAs=WebCodecsVideoDecoder] constructor(VideoDecoderInit init);

  // The number of pending decode requests. This does not include requests that
  // have been sent to the underlying codec.
  //
  // Applications can minimize underflow by enqueueing decode requests until
  // |decodeQueueSize| is greater than a constant.
  //
  // TODO(sandersd): Consider adding a predicted output count or other
  // backpressure mechanism that considers the state of the underlying codec.
  // TODO(sandersd): Consider emitting an event when this number decreases.
  readonly attribute long decodeQueueSize;

  // Which state the decoder is in, indicating which methods can be called.
  readonly attribute CodecState state;

  // Set the stream configuration for future decode() requests.
  //
  // The next decode request must be for a keyframe.
  //
  // TODO(sandersd): Move the keyframe rule into the bytestream registry.
  [RaisesException] void configure(VideoDecoderConfig config);

  // Request decoding of an input chunk.
  //
  // You must call configure() before calling decode() for the first time.
  [RaisesException] void decode(EncodedVideoChunk chunk);

  // Request output from all previous decode requests.
  //
  // Resolved after all output for earlier decode requests has been emitted.
  //
  // The next decode request must be for a keyframe.
  //
  // TODO(sandersd): Consider relaxing the keyframe requirement.
  // TODO(sandersd): Indicate whether the flush() completed successfully or due
  // to a reset.
  [RaisesException] Promise<void> flush();

  // Discard all pending decode requests.
  //
  // The next decode request must be for a keyframe.
  //
  // Note: It may be possible to call reset() after a flush() promise has been
  // resolved but before it is fulfilled. In that case the flush() promise will
  // be fulfilled successfully even though reset() was called.
  [RaisesException] void reset();

  // Immediately shut down the decoder and free its resources. All pending
  // decode requests are aborted.
  //
  // Not recoverable: make a new VideoDecoder if needed.
  [RaisesException] void close();

  // Call prior to configure() to determine whether config will be supported.
  [CallWith=ScriptState, RaisesException]
  static Promise<VideoDecoderSupport> isConfigSupported(VideoDecoderConfig config);
};