# WebCodecs

## Draft Community Group Report, 1 January 1970

This version:
  https://wicg.github.io/web-codecs/
Editors:
  Chris Cunningham (Google Inc.)
  Paul Adenot (Mozilla)
Participate:
  Git Repository.
  File an issue.
Version History:
  https://github.com/wicg/web-codecs/commits

Copyright © 1970 the Contributors to the WebCodecs Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

## Abstract

WebCodecs is a flexible web API for encoding and decoding audio and video.

## Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

## 1. Introduction

This section is non-normative

The introduction has not yet been written.

NOTE: The interfaces that follow are a work in progress.

## 2. VideoDecoder Interface

    [Exposed=(Window)]
    interface VideoDecoder {
        Promise<void> Initialize(VideoDecoderInitParameters params);
        Promise<void> Flush();
        void Close();

        readonly attribute WritableStream writable;  // of EncodedVideoFrame
        readonly attribute ReadableStream readable;  // of VideoFrame
    };

    [Exposed=(Window)]
    dictionary VideoDecoderInitParameters {
      required DOMString codec;
      required DOMString profile;

      // These are the "coded size", not the "visible size"
      required unsigned long width;
      required unsigned long height;
    };

## 3. VideoEncoder Interface

    [Exposed=(Window)]
    interface VideoEncoder {
      Promise<void> Initialize(VideoEncoderInitParameters params);
      void Close();

      readonly attribute WritableStream writable;  // of VideoFrame
      readonly attribute ReadableStream readable;  // of EncodedVideoFrame
    };

    enum VideoEncoderHardwareMode {
      "hardware",
      "software"
    };

    [Exposed=(Window)]
    dictionary VideoEncoderInitParameters {
      required VideoEncoderHardwareMode hardware_mode;
      required DOMString codec;
      required DOMString profile;

      required unsigned long visible_width;
      required unsigned long visible_height;

      required unsigned long bitsPerSecond;
      required double framesPerSecond;

      required double maxFramesBetweenKeyFrames;
    };

## Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with `class="example"`, like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with `class="note"`, like this:

Note, this is an informative note.

## Index

### Terms defined by this specification

- bitsPerSecond, in §3
- Close()
  - method for VideoDecoder, in §2
  - method for VideoEncoder, in §3
- codec
  - dict-member for VideoDecoderInitParameters, in §2
  - dict-member for VideoEncoderInitParameters, in §3
- Flush(), in §2
- framesPerSecond, in §3
- "hardware", in §3
- hardware_mode, in §3
- height, in §2
- Initialize(params)
  - method for VideoDecoder, in §2
  - method for VideoEncoder, in §3
- maxFramesBetweenKeyFrames, in §3
- profile
  - dict-member for VideoDecoderInitParameters, in §2
  - dict-member for VideoEncoderInitParameters, in §3
- readable
  - attribute for VideoDecoder, in §2
  - attribute for VideoEncoder, in §3
- "software", in §3
- VideoDecoder, in §2
- VideoDecoderInitParameters, in §2
- VideoEncoder, in §3
- VideoEncoderHardwareMode, in §3
- VideoEncoderInitParameters, in §3
- visible_height, in §3
- visible_width, in §3
- width, in §2
- writable
  - attribute for VideoDecoder, in §2
  - attribute for VideoEncoder, in §3

https://fetch.spec.whatwg.org/#concept-readablestream Referenced in:

- 2. VideoDecoder Interface
- 3. VideoEncoder Interface

https://streams.spec.whatwg.org/#ws-class Referenced in:

- 2. VideoDecoder Interface
- 3. VideoEncoder Interface

https://heycam.github.io/webidl/#idl-DOMString Referenced in:

- 2. VideoDecoder Interface (2)
- 3. VideoEncoder Interface (2)

https://heycam.github.io/webidl/#Exposed Referenced in:

- 2. VideoDecoder Interface (2)
- 3. VideoEncoder Interface (2)

https://heycam.github.io/webidl/#idl-double Referenced in:

- 3. VideoEncoder Interface (2)

https://heycam.github.io/webidl/#idl-unsigned-long Referenced in:

- 2. VideoDecoder Interface (2)
- 3. VideoEncoder Interface (2) (3)

### Terms defined by reference

- [FETCH] defines the following terms:
  - ReadableStream
- [STREAMS] defines the following terms:
  - WritableStream
- [WebIDL] defines the following terms:
  - DOMString
  - Exposed
  - double
  - unsigned long

## References

### Normative References

[FETCH]
  Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[RFC2119]
  S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[STREAMS]
  Adam Rice; Domenic Denicola; 吉野剛史 (Takeshi Yoshino). Streams Standard. Living Standard. URL: https://streams.spec.whatwg.org/
[WebIDL]
  Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

## IDL Index

    [Exposed=(Window)]
    interface VideoDecoder {
        Promise<void> Initialize(VideoDecoderInitParameters params);
        Promise<void> Flush();
        void Close();

        readonly attribute WritableStream writable;  // of EncodedVideoFrame
        readonly attribute ReadableStream readable;  // of VideoFrame
    };

    [Exposed=(Window)]
    dictionary VideoDecoderInitParameters {
      required DOMString codec;
      required DOMString profile;

      // These are the "coded size", not the "visible size"
      required unsigned long width;
      required unsigned long height;
    };

    [Exposed=(Window)]
    interface VideoEncoder {
      Promise<void> Initialize(VideoEncoderInitParameters params);
      void Close();

      readonly attribute WritableStream writable;  // of VideoFrame
      readonly attribute ReadableStream readable;  // of EncodedVideoFrame
    };

    enum VideoEncoderHardwareMode {
      "hardware",
      "software"
    };

    [Exposed=(Window)]
    dictionary VideoEncoderInitParameters {
      required VideoEncoderHardwareMode hardware_mode;
      required DOMString codec;
      required DOMString profile;

      required unsigned long visible_width;
      required unsigned long visible_height;

      required unsigned long bitsPerSecond;
      required double framesPerSecond;

      required double maxFramesBetweenKeyFrames;
    };

#dictdef-videodecoderinitparameters Referenced in:

- 2. VideoDecoder Interface

#enumdef-videoencoderhardwaremode Referenced in:

- 3. VideoEncoder Interface

#dictdef-videoencoderinitparameters Referenced in:

- 3. VideoEncoder Interface