Skip to content

Commit 569f64f

Browse files
chcunninghamchcunningham
committed
Define static async isConfigSupported()
Earlier drafts wrongly assumed that support could be determined synchronously.This remedies that by introducing a new async API to check support prior to calling configure(). Fixes #98. See additional discussion there.
1 parent aec3834 commit 569f64f

File tree

1 file changed

+117
-25
lines changed

1 file changed

+117
-25
lines changed

‎index.src.html

+117-25
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@
6262
Definitions {#definitions}
6363
==========================
6464

65-
: Codec
65+
: <dfn>Codec</dfn>
6666
:: Refers generically to an instance of AudioDecoder, AudioEncoder,
6767
VideoDecoder, or VideoEncoder.
6868

@@ -152,6 +152,8 @@
152152
Promise<undefined> flush();
153153
undefined reset();
154154
undefined close();
155+
156+
static Promise<boolean> isConfigSupported(AudioDecoderConfig config);
155157
};
156158

157159
dictionary AudioDecoderInit {
@@ -209,20 +211,27 @@
209211
<a>Enqueues a control message</a> to configure the audio decoder for
210212
decoding chunks as described by |config|.
211213

214+
NOTE: Authors should first check support by calling
215+
{{AudioDecoder/isConfigSupported()}} with |config| to avoid error paths
216+
in the steps below.
217+
212218
When invoked, run these steps:
213219
1. If |config| is not a <a>valid AudioDecoderConfig</a>, throw a
214220
{{TypeError}}.
215221
2. If {{AudioDecoder/state}} is `“closed”`, throw an {{InvalidStateError}}.
216-
3. If the user agent cannot provide a codec implementation to support
217-
|config|, throw a {{NotSupportedError}}.
218-
4. Set {{AudioDecoder/state}} to `"configured"`.
219-
5. <a>Queue a control message</a> to configure the decoder with |config|.
220-
6. <a>Run the control message processing loop</a>.
222+
3. Set {{AudioDecoder/state}} to `"configured"`.
223+
4. <a>Queue a control message</a> to configure the decoder with |config|.
224+
5. <a>Run the control message processing loop</a>.
221225

222226
<a>Running a control message</a> to configure the decoder means running
223227
these steps:
224-
1. Assign {{AudioDecoder/[[codec implementation]]}} with an implementation
228+
1. Let |supported| be the result of running the <a>Check Configuration
229+
Support</a> algorith with |config|.
230+
2. If |supported| is `true`, assign
231+
{{AudioDecoder/[[codec implementation]]}} with an implementation
225232
supporting |config|.
233+
3. Otherwise, run the <a>Close AudioDecoder</a> algorithm with
234+
{{NotSupportedError}}.
226235
</dd>
227236

228237
<dt><dfn method for=AudioDecoder>decode(chunk)</dfn></dt>
@@ -288,6 +297,17 @@
288297

289298
When invoked, run the <a>Close AudioDecoder</a> algorithm.
290299
</dd>
300+
301+
<dt><dfn method for=AudioDecoder>isConfigSupported(config)</dfn></dt>
302+
<dd>
303+
When invoked, run these steps:
304+
1. If |config| is not a <a>valid AudioDecoderConfig</a>, return
305+
[=a promise rejected with=] {{TypeError}}.
306+
2. Let |p| be a new Promise.
307+
3. [=In parallel=], run the <a>Check Configuration Support</a> algorithm
308+
with |config| and resolve |p| with its result.
309+
4. Return p.
310+
</dd>
291311
</dl>
292312

293313
Algorithms {#audiodecoder-algorithms}
@@ -340,6 +360,8 @@
340360
Promise<undefined> flush();
341361
undefined reset();
342362
undefined close();
363+
364+
static Promise<boolean> isConfigSupported(VideoDecoderConfig config);
343365
};
344366

345367
dictionary VideoDecoderInit {
@@ -397,20 +419,27 @@
397419
<a>Enqueues a control message</a> to configure the video decoder for
398420
decoding chunks as described by |config|.
399421

422+
NOTE: Authors should first check support by calling
423+
{{VideoDecoder/isConfigSupported()}} with |config| to avoid error paths
424+
in the steps below.
425+
400426
When invoked, run these steps:
401427
1. If |config| is not a <a>valid VideoDecoderConfig</a>, throw a
402428
{{TypeError}}.
403429
2. If {{VideoDecoder/state}} is `“closed”`, throw an {{InvalidStateError}}.
404-
3. If the user agent cannot provide a codec implementation to support
405-
|config|, throw a {{NotSupportedError}}.
406-
4. Set {{VideoDecoder/state}} to `"configured"`.
407-
5. <a>Queue a control message</a> to configure the decoder with |config|.
408-
6. <a>Run the control message processing loop</a>.
430+
3. Set {{VideoDecoder/state}} to `"configured"`.
431+
4. <a>Queue a control message</a> to configure the decoder with |config|.
432+
5. <a>Run the control message processing loop</a>.
409433

410434
<a>Running a control message</a> to configure the decoder means running
411435
these steps:
412-
1. Assign {{VideoDecoder/[[codec implementation]]}} with an implementation
436+
1. Let |supported| be the result of running the <a>Check Configuration
437+
Support</a> algorith with |config|.
438+
2. If |supported| is `true`, assign
439+
{{VideoDecoder/[[codec implementation]]}} with an implementation
413440
supporting |config|.
441+
3. Otherwise, run the <a>Close VideoDecoder</a> algorithm with
442+
{{NotSupportedError}}.
414443
</dd>
415444

416445
<dt><dfn method for=VideoDecoder>decode(chunk)</dfn></dt>
@@ -477,6 +506,17 @@
477506

478507
When invoked, run the <a>Close VideoDecoder</a> algorithm.
479508
</dd>
509+
510+
<dt><dfn method for=VideoDecoder>isConfigSupported(config)</dfn></dt>
511+
<dd>
512+
When invoked, run these steps:
513+
1. If |config| is not a <a>valid VideoDecoderConfig</a>, return
514+
[=a promise rejected with=] {{TypeError}}.
515+
2. Let |p| be a new Promise.
516+
3. [=In parallel=], run the <a>Check Configuration Support</a> algorithm
517+
with |config| and resolve |p| with its result.
518+
4. Return p.
519+
</dd>
480520
</dl>
481521

482522
Algorithms {#videodecoder-algorithms}
@@ -546,6 +586,8 @@
546586
Promise<undefined> flush();
547587
undefined reset();
548588
undefined close();
589+
590+
static Promise<boolean> isConfigSupported(AudioEncoderConfig config);
549591
};
550592

551593
dictionary AudioEncoderInit {
@@ -603,20 +645,27 @@
603645
<a>Enqueues a control message</a> to configure the audio encoder for
604646
decoding chunks as described by |config|.
605647

648+
NOTE: Authors should first check support by calling
649+
{{AudioEncoder/isConfigSupported()}} with |config| to avoid error paths
650+
in the steps below.
651+
606652
When invoked, run these steps:
607653
1. If |config| is not a <a>valid AudioEncoderConfig</a>, throw a
608654
{{TypeError}}.
609655
2. If {{AudioEncoder/state}} is `"closed"`, throw an {{InvalidStateError}}.
610-
3. If the user agent cannot provide a codec implementation to support
611-
|config|, throw a {{NotSupportedError}}.
612-
4. Set {{AudioEncoder/state}} to `"configured"`.
613-
5. <a>Queue a control message</a> to configure the encoder using |config|.
614-
6. <a>Run the control message processing loop</a>.
656+
3. Set {{AudioEncoder/state}} to `"configured"`.
657+
4. <a>Queue a control message</a> to configure the encoder using |config|.
658+
5. <a>Run the control message processing loop</a>.
615659

616660
Running a control message to configure the encoder means performing these
617661
steps:
618-
1. Assign {{AudioEncoder/[[codec implementation]]}} with an implementation
662+
1. Let |supported| be the result of running the <a>Check Configuration
663+
Support</a> algorith with |config|.
664+
2. If |supported| is `true`, assign
665+
{{AudioEncoder/[[codec implementation]]}} with an implementation
619666
supporting |config|.
667+
3. Otherwise, run the <a>Close AudioEncoder</a> algorithm with
668+
{{NotSupportedError}}.
620669
</dd>
621670

622671
<dt><dfn method for=AudioEncoder>encode(frame)</dfn></dt>
@@ -691,6 +740,17 @@
691740

692741
When invoked, run the <a>Close AudioEncoder</a> algorithm.
693742
</dd>
743+
744+
<dt><dfn method for=AudioEncoder>isConfigSupported(config)</dfn></dt>
745+
<dd>
746+
When invoked, run these steps:
747+
1. If |config| is not a <a>valid AudioEncoderConfig</a>, return
748+
[=a promise rejected with=] {{TypeError}}.
749+
2. Let |p| be a new Promise.
750+
3. [=In parallel=], run the <a>Check Configuration Support</a> algorithm
751+
with |config| and resolve |p| with its result.
752+
4. Return p.
753+
</dd>
694754
</dl>
695755

696756
Algorithms {#audioencoder-algorithms}
@@ -748,6 +808,8 @@
748808
Promise<undefined> flush();
749809
undefined reset();
750810
undefined close();
811+
812+
static Promise<boolean> isConfigSupported(VideoEncoderConfig config);
751813
};
752814

753815
dictionary VideoEncoderInit {
@@ -812,20 +874,27 @@
812874
<a>Enqueues a control message</a> to configure the video encoder for
813875
decoding chunks as described by |config|.
814876

877+
NOTE: Authors should first check support by calling
878+
{{VideoEncoder/isConfigSupported()}} with |config| to avoid error paths
879+
in the steps below.
880+
815881
When invoked, run these steps:
816882
1. If |config| is not a <a>valid VideoEncoderConfig</a>, throw a
817883
{{TypeError}}.
818884
2. If {{VideoEncoder/state}} is `"closed"`, throw an {{InvalidStateError}}.
819-
3. If the user agent cannot provide a codec implementation to support
820-
|config|, throw a {{NotSupportedError}}.
821-
4. Set {{VideoEncoder/state}} to `"configured"`.
822-
5. <a>Queue a control message</a> to configure the encoder using |config|.
823-
6. <a>Run the control message processing loop</a>.
885+
3. Set {{VideoEncoder/state}} to `"configured"`.
886+
4. <a>Queue a control message</a> to configure the encoder using |config|.
887+
5. <a>Run the control message processing loop</a>.
824888

825889
Running a control message to configure the encoder means performing these
826890
steps:
827-
1. Assign {{VideoEncoder/[[codec implementation]]}} with an implementation
891+
1. Let |supported| be the result of running the <a>Check Configuration
892+
Support</a> algorith with |config|.
893+
2. If |supported| is `true`, assign
894+
{{VideoEncoder/[[codec implementation]]}} with an implementation
828895
supporting |config|.
896+
3. Otherwise, run the <a>Close VideoEncoder</a> algorithm with
897+
{{NotSupportedError}} and abort these steps.
829898
2. Set {{VideoEncoder/[[active encoder config]]}} to `config`.
830899
</dd>
831900

@@ -901,6 +970,17 @@
901970

902971
When invoked, run the <a>Close VideoEncoder</a> algorithm.
903972
</dd>
973+
974+
<dt><dfn method for=VideoEncoder>isConfigSupported(config)</dfn></dt>
975+
<dd>
976+
When invoked, run these steps:
977+
1. If |config| is not a <a>valid VideoEncoderConfig</a>, return
978+
[=a promise rejected with=] {{TypeError}}.
979+
2. Let |p| be a new Promise.
980+
3. [=In parallel=], run the <a>Check Configuration Support</a> algorithm
981+
with |config| and resolve |p| with its result.
982+
4. Return p.
983+
</dd>
904984
</dl>
905985

906986
Algorithms {#videoencoder-algorithms}
@@ -979,6 +1059,18 @@
9791059
Configurations{#configurations}
9801060
===============================
9811061

1062+
<dfn>Check Configuration Support</dfn> (with |config|) {#config-support}
1063+
------------------------------------------------------------------------
1064+
1. If the user agent can provide a <a>codec</a> to support all entries of the
1065+
|config|, including applicable default values for keys that are not
1066+
included, return `true`.
1067+
1068+
NOTE: The types {{AudioDecoderConfig}}, {{VideoDecoderConfig}},
1069+
{{AudioEncoderConfig}}, and {{VideoEncoderConfig}} each define their
1070+
respective configuration entries and defaults.
1071+
1072+
2. Otherwise, return false.
1073+
9821074
<dfn export>Codec String</dfn>{#config-codec-string}
9831075
----------------------------------------------------
9841076
In other media specifications, codec strings historically accompanied a

0 commit comments

Comments
 (0)