/
index.bs
2053 lines (1560 loc) · 88.9 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class='metadata'>
Title: Open Screen Protocol
Shortname: openscreenprotocol
Level: 1
Status: w3c/ED
ED: https://webscreens.github.io/openscreenprotocol/
Canonical URL: ED
Editor: Mark Foltz, Google, https://github.com/mfoltzgoogle, w3cid 68454
Repository: webscreens/openscreenprotocol
Abstract: The Open Screen Protocol is a suite of network protocols that allow
user agents to implement the [[PRESENTATION-API|Presentation API]] and
the [[REMOTE-PLAYBACK|Remote Playback API]] in an interoperable
fashion.
Group: Second Screen Community Group
Mailing List: public-webscreens@w3c.org
Mailing List Archives: https://lists.w3.org/Archives/Public/public-webscreens/
Markup Shorthands: markdown yes, dfn yes, idl yes
</pre>
<p boilerplate="copyright">
<a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">
Copyright</a> © [YEAR] the Contributors to the [TITLE] Specification,
published by the <a href="https://www.w3.org/community/webscreens/">
Second Screen Community Group</a> under the
<a href="https://www.w3.org/community/about/agreements/cla/">
W3C Community Contributor License Agreement (CLA)</a>. A human-readable
<a href="http://www.w3.org/community/about/agreements/cla-deed/">summary</a>
is available.
</p>
Issue: Add short names to Presentation API spec, so that BS autolinking works as designed.
Issue: Can autolinks to HTML51 be automatically generated?
<pre class="anchors">
urlPrefix: https://w3c.github.io/presentation-api/#dfn-; type: dfn; spec: PRESENTATION-API
text: available presentation display
text: controller
text: controlling user agent
text: controlling browsing context
text: presentation
text: presentation display
text: presentation display availability
text: presentation id
text: presentation request url
text: receiver
text: receiving browsing context
text: receiving user agent
text: available presentation display
urlPrefix: https://w3c.github.io/presentation-api/; type: interface; spec: PRESENTATION-API
text: PresentationConnection
urlPrefix: https://w3c.github.io/remote-playback/#dfn-; type: dfn; spec: REMOTE-PLAYBACK
text: availability sources set
text: compatible remote playback device
text: media element state
text: media resources
text: remote playback devices
text: remote playback source
urlPrefix: https://www.w3.org/TR/html51/single-page.html; type: dfn; spec: HTML51
text: media element
</pre>
<h2 class='no-num no-toc no-ref' id='status'>Status of this document</h2>
This specification was published by the [Second Screen Community
Group](https://www.w3.org/community/webscreens/). It is not a W3C Standard nor
is it on the W3C Standards Track. It should not be viewed as a stable
specification, and may change in substantial ways at any time. A future version
of this document will be published as a Community Group Report.
Please note that under the [W3C Community Contributor License Agreement
(CLA)](https://www.w3.org/community/about/agreements/cla/) there is a limited
opt-out and other conditions apply.
Learn more about [W3C Community and Business
Groups](http://www.w3.org/community/).
Introduction {#introduction}
============================
The Open Screen Protocol connects browsers to devices capable of rendering Web
content for a shared audience. Typically, these are devices like
Internet-connected TVs, HDMI dongles, or "smart" speakers.
The protocol is a suite of subsidiary network protocols that enable two user
agents to implement the [[PRESENTATION-API|Presentation API]] and
[[REMOTE-PLAYBACK|Remote Playback API]] in an interoperable fashion. This means
that a user can expect these APIs work as intended when connecting two devices
from independent implementations of the Open Screen Protocol.
The Open Screen Protocol is a specific implementation of these two APIs, meaning
that it does not handle all possible ways that browsers and presentation
displays could support these APIs. The Open Screen Protocol specifically
supports browsers and displays that are connected via the same local area
network, and that initiate presentation or remote playback by sending a URL
from the browser to the target display.
The Open Screen Protocol is intended to be extensible, so that additional
capabilities can be added over time. This may include new implementations of
existing APIs, or new APIs.
Terminology {#terminology}
--------------------------
We use the term "agent" to mean any implementation of this protocol
(browser, device, or otherwise), acting as a controller or a receiver.
We borrow terminology from the [[PRESENTATION-API|Presentation API]]. We call
the agent that is used to discover and initiate presentation of Web content on
another device the [=controller=] (or [=controlling user agent=] when it is a
browser). We call the agent on the device rendering the Web content the
[=receiver=] or [=presentation display=] (or [=receiving user agent=] when it is
a browser). [=presentation display availability=] refers to whether or not a
[=receiver=] is compatible with a [=presentation request URL=]. However, in the
[[PRESENTATION-API|Presentation API]], a "controller" refers to as a specific
browsing context within the browser, whereas here the "controller" refers to the
browser itself, although it may be acting on behalf of a browsing context.
We borrow terminology from the [[REMOTE-PLAYBACK|Remote Playback API]]. The
agent responsible for rendering media of a remote playback is called the
[=remote playback device=]. In this document, we also refer to it as the
*receiver* because it is shorter and keeps terminology consistent between
presentations and remote playbacks. Similarly, we use the term "controller"
(referred to as the "user agent" in the [[REMOTE-PLAYBACK|Remote Playback API]])
to refer to the agent that starts, terminates, and controls the remote playback.
For media streaming, we refer to the agent sending media as the media
*sender* and the agent receiving the media as the media *receiver*.
Note that a media *receiver* may or may not be a *receiver* or
*controller* as defined by the Presentation API or Remote Playback
API. Also note that an agent may be both a *sender* and *receiver*.
For additional terms and idioms specific to the [[PRESENTATION-API|Presentation
API]] or [[REMOTE-PLAYBACK|Remote Playback API]], please consult the respective
specifications.
Issue(144): Receiver/Controller/Agent terminology.
Requirements {#requirements}
============================
Presentation API Requirements {#requirements-presentation-api}
--------------------------------------------------------------
1. A controlling user agent must be able to discover the presence of a
presentation display connected to the same IPv4 or IPv6 subnet and reachable
by IP multicast.
2. A controlling user agent must be able to obtain the IPv4 or IPv6 address of
the display, a friendly name for the display, and an IP port number for
establishing a network transport to the display.
3. A controlling user agent must be able to determine if the receiver is
reasonably capable of rendering a specific [=presentation request URL=].
4. A controlling user agent must be able to start a new presentation on a receiver given a
[=presentation request URL=] and [=presentation ID=].
5. A controlling user agent must be able to create a new
{{PresentationConnection}} to an existing presentation on the
receiver, given its [=presentation request URL=] and [=presentation ID=].
6. It must be possible to close a {{PresentationConnection}} between a
controller and a presentation, and signal both parties with the
reason why the connection was closed.
7. Multiple controllers must be able to connect to a single presentation
simultaneously, possibly from from one or more [=controlling user agents=].
8. Messages sent by the controller must be delivered to the presentation (or
vice versa) in a reliable and in-order fashion.
9. If a message cannot be delivered, then the controlling user agent must be
able to signal the receiver (or vice versa) that the connection should be
closed with reason `error`.
10. The controller and presentation must be able to send and receive `DOMString`
messages (represented as `string` type in ECMAScript).
11. The controller and presentation must be able to send and receive binary
messages (represented as `Blob` objects in HTML5, or `ArrayBuffer` or
`ArrayBufferView` types in ECMAScript).
12. The controlling user agent must be able to signal to the receiver to
terminate a presentation, given its [=presentation request URL=] and [=presentation
ID=].
13. The receiver must be able to signal all connected controlling user agents
when a presentation is terminated.
Remote Playback API Requirements {#requirements-remote-playback}
----------------------------------------------------------------
1. A [=controlling user agent=] must be able to find out whether there is at
least one compatible [=remote playback device=] available for a given
{{HTMLMediaElement}}, both instantaneously and continuously.
2. A controlling user agent must be able to start sending the content of an
{{HTMLMediaElement}} to a compatible remote playback device.
3. The controlling user agent should be able to send both media data
and text tracks from an {{HTMLMediaElement}} to the remote playback device.
4. During remote playback, the controlling user agent and the remote playback
device must be able to synchronize the [=media element state=] of the
{{HTMLMediaElement}}.
5. During remote playback, either the controlling user agent or the
remote playback device must be able to disconnect from the other party.
6. The controlling user agent should be able to pass locale and text
direction information to the remote playback device to assist in rendering
text during remote playback.
Non-Functional Requirements {#requirements-non-functional}
----------------------------------------------------------
1. It should be possible to implement an Open Screen presentation display using
modest hardware requirements, similar to what is found in a low end
smartphone, smart TV or streaming device. See the [Device
Specifications](device_specs.md) document for expected presentation display
hardware specifications.
2. It should be possible to implement an Open Screen controlling user agent on a
low-end smartphone. See the [Device Specifications](device_specs.md) document
for expected controlling user agent hardware specifications.
3. The discovery and connection protocols should minimize power consumption,
especially on the controlling user agent which is likely to be battery
powered.
4. The protocol should minimize the amount of information provided to a passive
network observer about the identity of the user, activity on the controlling
user agent and activity on the receiver.
5. The protocol should prevent passive network eavesdroppers from learning
presentation URLs, presentation IDs, or the content of presentation messages
passed between controllers and presentations.
6. The protocol should prevent active network attackers from impersonating a
display and observing or altering data intended for the controller or
presentation.
7. The controlling user agent should be able to discover quickly when a
presentation display becomes available or unavailable (i.e., when it connects
or disconnects from the network).
8. The controlling user agent should present sensible information to the user
when a protocol operation fails. For example, if a controlling user agent is
unable to start a presentation, it should be possible to report in the
controlling user agent interface if it was a network error, authentication
error, or the presentation content failed to load.
9. The controlling user agent should be able to remember authenticated
presentation displays. This means it is not required for the user to
intervene and re-authenticate each time the controlling user agent connects
to a pre-authenticated display.
10. Message latency between the controller and a presentation should be minimized
to permit interactive use. For example, it should be comfortable to type in
a form in the controller and have the text appear in the presentation in real
time. Real-time latency for gaming or mouse use is ideal, but not a
requirement.
11. The controlling user agent initiating a presentation should communicate its
preferred locale to the receiver, so it can render the presentation content
in that locale.
12. It should be possible to extend the control protocol (above the discovery and
transport levels) with optional features not defined explicitly by the
specification, to facilitate experimentation and enhancement of the base
APIs.
Discovery with mDNS {#discovery}
===============================
Agents may discover one another using [[RFC6763|DNS-SD]] over [[RFC6762|mDNS]].
To do so, agents must use the service name "_openscreen._udp.local".
Issue(107): Define suspend and resume behavior for discovery protocol.
Advertising Agents must use an instance name that is a prefix of the agent's
display name. If the instance name is not the complete display name (if it has
been truncated), it must be terminated by a null character. It is prefix so
that the name displayed to the user pre-verification can be verified later. It
is terminated by a null character in the case of truncation so that the
listening agent knows it has been truncated. This complexity is necessary to
all for display names that exceed the size allowed in an instance name and for
such (possibly truncated) display names to be visible to the user sooner
(before a QUIC connection is made). Listening agents must treat instance names
as unverified and must verify that the instance name is a prefix of the verified
display name before showing the user a verified display name.
Advertising agents must include DNS TXT records with the following
keys and values:
: fp
:: The certificate fingerprint of the advertising agent.
The format of the fingerprint is defined by [RFC 8122 section
5](https://tools.ietf.org/html/rfc8122#section-5), excluding the
"fingerprint:" prefix and including the hash function, space, and hex-encoded
fingerprint. The fingerprint value also functions as an ID for the agent.
All agents must support the following hash functions: "sha-256", "sha-512".
Agents must not support the following hash functions: "md2", "md5".
Issue: Include cross references to the specs for these hash functions.
: mv
:: An unsigned integer value that indicates that
metadata has changed. The advertising agent must update it to a greater
value. This signals to the listening agent that it should connect to the
advertising agent to discover updated metadata.
Issue: Add examples of sample mDNS records.
Future extensions to this QUIC-based protocol can use the same metadata
discovery process to indicate support for those extensions, through a
capabilities mechanism to be determined. If a future version of the Open Screen
Protocol uses mDNS but breaks compatibility with the metadata discovery process,
it should change the DNS-SD service name to a new value, indicating a new
mechanism for metadata discovery.
Transport and metadata discovery with QUIC {#transport}
=======================================================
If an agent wants to connect to or learn further metadata about another agent,
it initiates a [[QUIC]] connection to the IP and port from the SRV record.
Prior to authentication, a message may be exchanged (such as further metadata),
but such info should be treated as unverified (such as indicating to a user that
a display name of an unauthenticated agent is unverified).
To learn further metadata, an agent may send an agent-info-request
message (see [[#appendix-a]]) and receive back an agent-info-response message.
Any agent may send this request to learn about the capabilities of
another device.
The agent-info-response message contains the following properties:
: display-name (required)
:: The display name of the agent, intended to be displayed to a user by the
requester. The requester should indicate through the UI if the responder
is not authenticated or if the display name changes.
: model-name (optional)
:: If the agent is a hardware device, the model name of
the device. This is used mainly for debugging purposes, but may be
displayed to the user of the requesting agent.
: receives-audio (optional)
:: The agent has to indicate that it supports audio. If false
or not included, it is assumed audio content is not supported.
: receives-video (optional)
:: The agent has to indicate that it supports video . If false
or not included, it is assumed video content is not supported.
Listening agents act as QUIC clients. Advertising agents act as QUIC servers.
If a listening agent wishes to receive messages from an advertising agent or an
advertising agent wishes to send messages to a listening agent, it may wish to
keep the QUIC connection alive. Once neither side needs to keep the connection
alive for the purposes of sending or receiving messages, the connection should
be closed with an error code of 5139. In order to keep a QUIC connection alive, an
agent may send an agent-status-request message, and any agent that receives an
agent-status-request message should send an agent-status-response message. Such
messages should be sent more frequently than the QUIC idle_timeout transport
parameter (see section 18 of [[QUIC]]) and QUIC PING
frames should not be used. An idle_timeout transport parameter of 25 seconds is
recommended. The agent should behave as though a timer less than the
idle_timeout were reset every time a message is sent on a QUIC stream. If the
timer expires, a agent-status-request message should be sent.
If a client agent wishes to send messages to a server agent, the client
agent can connect to the server agent "on demand"; it does not need to
keep the connection alive.
Issue(108): Define suspend and resume behavior for connection protocol.
The agent-info-response message and agent-status-response messages may be
extended to include additional information not defined in this spec. If done
ad-hoc by applications and not in future specs, keys should be chosen to avoid
collision, such as by choosing large integers or long strings. Agents must
ignore keys in the agent-info-message that it does not understand to allow
agents to easily extend this message.
Messages delivery using CBOR and QUIC streams {#messages}
========================================================
Messages are serialized using [[RFC7049|CBOR]]. To
send a group of messages in order, that group of messages must be sent in one
QUIC stream. Independent groups of messages (with no ordering dependency
across groups) should be sent in different QUIC streams. In order to put
multiple CBOR-serialized messages into the the same QUIC stream, the following
is used.
For each message, the sender must write to the QUIC stream the following:
1. A type key representing the type of the message, encoded as a variable-length
integer (see [[#appendix-a]] for type keys)
2. The message encoded as CBOR.
If an agent receives a message for which it does not recognize a
type key, it must close the QUIC connection with an application error
code of 404 and should include the unknown type key in the reason phrase
(see [[QUIC#section-19.4|QUIC transport section 19.4]]).
Variable-length integers are encoded in the same format as defined by
[[QUIC#section-16| QUIC transport section 16]].
Many messages are requests and responses, so a common format is defined for
those. A request and a response includes a request ID which is an unsigned
integer chosen by the requester. Responses must include the request ID of the
request they are associated with.
Issue(139): Clarify scoping/uniqueness of request IDs.
Authentication {#authentication}
================================
Each supported authentication method is implemeted via authentication messages
specific to that method. The authentication method is explicitly specified by
the message itself. The authentication status message is common for all authentication
methods. Any new authentication method added must define new authentication messages.
The default authentication method is a challenge-response authentication with
auth-request-hkdf-scrypt-psk and auth-response-hkdf-scrypt-psk-result.
Prior to authentication, agents exchange auth-capabilities messages specifying
pre-shared key (PSK) ease of input for the user and supported PSK input methods.
The agent with the lowest PSK ease of input presents a PSK to the user when the agent
either sends or receives an authentication request. In case both agents have the same
PSK ease of input value, the server presents the PSK to the user. The same pre-shared key
is used by both agents to issue an authentication request.
PSK ease of input is an integer in the range from 0 to 100 inclusive, where 0 means
it is not possible for the user to input PSK on this device and 100 means
that it's easy for the user to input PSK on the device. Supported PSK input methods
are numeric and scanning a QR-code. Devices with non-zero PSK ease of input must
support the numeric PSK input method.
In order for one agent (the challenger) to authenticate another (the responder),
the challenger may send an authentication-request message and expect an
authentication-response message to be sent back from the responder. To
mutually authenticate, this mechanism is used twice, once by each side acting as
the challenger. This mechanism assumes the agents share a low-entropy secret,
such as a number or a short password that could be entered by a user on a
keyboard or TV remote control.
For all messages and objects defined in this section, see Appendix A for the full
CDDL definitions.
The challenger sends an auth-request-hkdf-scrypt-psk message with the following values:
- salt: 32 random bytes. This salt is used in HKDF, so see
https://tools.ietf.org/html/rfc5869#section-3.1 for more details on how this
value should be generated.
- cost: log base 2 of the cost parameter (N) for scrypt defined in [RFC
7914 section 2](https://tools.ietf.org/html/rfc7914#section-2). It must be
greater than or equal to 14 (to avoid being too weak) and less than or equal
to 128 (the limit defined by scrypt). A value of 15 is recommended (an
scrypt N of 2^15 or 32768).
The responder replies with an auth-response-hkdf-scrypt-psk-result message with
the following values:
- result: If the responder was able to calculate proof of possession of the
shared secret, and if it failed, why it failed.
- proof: The result of running the authentication mechanism. The steps for
hkdf-of-scrypt-of-psk are described below.
The challenger verifies the proof and sends the responder an auth-status message
with the following values:
- result: If the challenger was able to authenticate the responder or not,
and if not, why not.
The challenger must limit the time the responder has to send a response to 60
seconds (to avoid the possibility of brute-force attacks.)
For hkdf-of-scrypt-of-psk, the proof is calculated using the following steps:
1. Let secret be the pre-shared secret.
2. Let N be 2 to the power of of the cost from the authentication-request
message.
3. Let r be 8.
4. Let p be 1.
5. Let keyLength be 32.
6. Let scryptResult be the result of running
[scrypt](https://tools.ietf.org/html/rfc7914) on secret with cost parameter N,
block size r, parallelization parameter p, and derived key length of
keyLength.
7. Let hashFunction be sha-256.
8. Let salt be the salt from the authentication-request message.
9. Let info be a 64-byte array containing certificate fingerprint pair with the following values:
- Bytes 0-31 of the array are the challenger's fingerprint: The result of running
sha-256 on the Distinguished Encoding Rules (DER) form (see
https://tools.ietf.org/html/rfc8122#section-5) of the certificate used by
the challenger in the QUIC crypto handshake during connection establishment.
- Bytes 32-63 of the array are the responder's fingerprint: The result of running
sha-256 on the Distinguished Encoding Rules (DER) form (see
https://tools.ietf.org/html/rfc8122#section-5) of the certificate used by
the responder in the QUIC crypto handshake during connection establishment.
9. Let proof be the result of running
[\HKDF](https://tools.ietf.org/html/rfc5869) on scryptResult with
both the extract and expand steps, hash function hashFunction,
application-specific info, and output key length keyLength.
To verify that the responder's proof is correct, the challenger makes the same
calculation of the proof and compares the result. If the results are the same,
the challenger considers the responder authenticated, and considers it
unauthenticated otherwise.
Note: the values of 32 above (for salt length, keyLength) are based on the
output size of sha-256. If a different hash mechanism is used in the future,
these values should be updated as well.
Control Protocols {#control-protocols}
============================
Presentation Protocol {#presentation-protocol}
---------------------------------------------
This section defines the use of the Open Screen Protocol for starting,
terminating, and controlling presentations as defined by
[[PRESENTATION-API|Presentation API]]. [[#presentation-api]]
defines how APIs in [[PRESENTATION-API|Presentation API]] map to the
protocol messages defined in this section.
For all messages defined in this section, see [[#appendix-a]] for the full
CDDL definitions.
Issue(123): Add a capability that indicates support for the presentation protocol.
Issue(160): Refinements to Presentation API protocol.
To learn which receivers are [=available presentation displays=] for a
particular URL or set of URLs, the controller may send a
presentation-url-availability-request message with the following values:
: urls
:: A list of presentation URLs. Must not be empty.
: watch-duration
:: The period of time that the controller is interested in receiving updates
about their URLs, should the availability change.
: watch-id
:: An identifier the receiver must use when sending updates about URL
availability so that the controller knows which URLs the receiver is referring
to. The controller must choose a value that is unique across all
presentation URL availability watches to the same receiver.
Issue(145): Watch ID Uniqueness.
In response, the receiver should send one presentation-url-availability-response
message with the following values:
: url-availabilities
:: A list of URL availability states. Each state must correspond to the matching URL
from the request by list index.
While the watch is valid (the watch-duration has not expired), the receivers
should send remote-playback-availability-event messages when URL availabilities change.
Such events contain the following values:
: watch-id
:: The watch-id given in the presentation-url-availability-response,
used to refer to the presentation URLs whose availability has changed.
: url-availabilities
:: A list of URL availability states. Each state must correspond to the URLs from the
request referred to by the watch-id.
Note that these messages are not broadcasted to all controllers. They are sent
individually to controllers that have requested availability for the URLs that
have changed in availability state within the watch duration of the original
availability request.
To save power, the controller may disconnect the QUIC connection and
later reconnect to send availability requests and receive availability
responses and updates. The QUIC connection ID may or may not be the same
when reconnecting. Note that the lifetime of a watch-id is not limited
to one QUIC connection. The receiver must continue sending updates for watches
even if the QUIC connection changes, and thus controller need not send
new URL availability requests if the QUIC connection changes.
To start a presentation, the controller may send a
presentation-start-request message to the receiver with the following
values:
: presentation-id
:: The presentation identifier
: url
:: The selected presentation URL
: headers
:: headers that the receiver should use to fetch the
presentationUrl. For example,
[[PRESENTATION-API#establishing-a-presentation-connection|section 6.6.1]] of
the Presentation API says that the Accept-Language header should be
provided.
The presentation ID must follow the restrictions defined by
[[PRESENTATION-API#common-idioms|section 6.1]] of the Presentation API, in that
it must consist of at least 16 ASCII characters.
When the receiver receives the presentation-start-request, it should send back a
presentation-start-response message after either the presentation URL has been
fetched and loaded, or the receiver has failed to do so. If it has failed, it
must respond with the appropriate result (such as invalid-url or timeout). If
it has succeeded, it must reply with a success result. Additionally, the
response must include the following:
: connection-id
:: An ID that both agents can use to send connection messages
to each other. It is chosen by the receiver for ease of implementation: if
the message receiver chooses the connection-id, it may keep the ID unique
across connections, thus making message demuxing/routing easier.
To send a presentation message, the controller or receiver may send a
presentation-connection-message with the following values:
: connection-id
:: The ID from the presentation-start-response or
presentation-connection-open-response messages.
: message
:: The presentation message data.
To terminate a presentation, the controller may send a
presentation-termination-request message with the following values:
: presentation-id
:: The ID of the presentation to terminate.
: reason
:: The reason the presentation is being terminated.
When a [=receiver=] receives a presentation-termination-request, it should
send back a presentation-termination-response message to the requesting
controller. It should also notify other controllers about the termination by sending
a presentation-termination-event message. And it can send the same message if
it terminates a presentation without a request from a controller to do so. This
message contains the following values:
: presentation-id
:: The ID of the presentation that was terminated.
: reason
:: The reason the presentation was terminated.
To accept incoming connections requests from controller, a receiver
must receive and process the presentation-connection-open-request
message which contains the following values:
: presentation-id
:: The ID of the presentation to connect to.
: url
:: The URL of the presentation to connect to.
The receiver should, upon receipt of a
presentation-connection-open-request message, send back a
presentation-connection-open-response message which contains the
following values:
: result
:: a code indicating success or failure, and the reason for the failure
: connection-id
:: An ID that both agents can use to send connection messages
to each other. It is chosen by the receiver for ease of implementation (if
the message receiver chooses the connection-id, it may keep the ID unique
across connections, thus making message demuxing/routing easier).
A controller may terminate a connection without terminating the presentation by
sending a presentation-connection-close-request message with the following
values:
: connection-id
:: The ID of the connection to close.
Issue(124): Is a Presentation close/terminate from a controller a request/response or event?
The receiver should, upon receipt of a presentation-connection-close-request,
send back a presentation-connection-close-response message with the following
values:
: result
:: If the close succeed or failed, and if it failed why it failed.
Issue(138): Remove presentation-connection-close-response message.
The receiver may also close a connection without a request from the controller
to do so and without terminating a presentation. If it does so, it should send
a presentation-connection-close-event to the controller with the following
values:
: connection-id
:: The ID of the connection that was closed
: reason
:: The reason the connection was closed
: error-message
:: A debug message suitable for a log or perhaps presented to
the user with more explanation as to why it was closed.
Presentation API {#presentation-api}
---------------------------------------------
This section defines how the [[PRESENTATION-API|Presentation API]] uses the
[[#presentation-protocol]].
When [[PRESENTATION-API#the-list-of-available-presentation-displays|section
6.4.2]] says "This list of presentation displays ... is populated based on an
implementation specific discovery mechanism", the [=controlling user agent=] may
use the mDNS, QUIC, agent-info-request, and
presentation-url-availability-request messages defined previously in this spec
to discover receivers.
When [[PRESENTATION-API#the-list-of-available-presentation-displays|section
6.4.2]] says "To further save power, ... implementation specific discovery of
presentation displays can be resumed or suspended.", the [=controlling user
agent=] may use the power saving mechanism defined in the previous section.
When [[PRESENTATION-API#starting-a-presentation-connection|section 6.3.4]] says
"Using an implementation specific mechanism, tell U to create a receiving
browsing context with D, presentationUrl, and I as parameters.", U (the
[=controlling user agent=]) may send a presentation-start-request message to D
(the receiver), with I for the presentation identifier and presentationUrl for
the selected presentation URL.
Issue: Once the Presentation API has text about reconnecting via an
implementation specific mechanism, quote that here and map it to a message.
When [[PRESENTATION-API#sending-a-message-through-presentationconnection|section
6.5.2]] says "Using an implementation specific mechanism, transmit the contents
of messageOrData as the presentation message data and messageType as the
presentation message type to the destination browsing context", the
[=controlling user agent=] may send a presentation-connection-message with
messageOrData for the presentation message data. Note that the messageType is
embedded in the encoded CBOR type and does not need an additional value in the
message.
When
[[PRESENTATION-API#terminating-a-presentation-in-a-controlling-browsing-context|section
6.5.6]] says "Send a termination request for the presentation to its receiving
user agent using an implementation specific mechanism", the [=controlling user
agent=] may send a presentation-termination-request message.
When [[PRESENTATION-API#monitoring-incoming-presentation-connections|section
6.7.1]]
says "it MUST listen to and accept incoming connection requests from a
controlling browsing context using an implementation specific
mechanism", the [=receiving user agent=] must receive and process the
presentation-connection-open-request.
When [[PRESENTATION-API#monitoring-incoming-presentation-connections|section
6.7.1]] says "Establish the connection between the controlling and receiving
browsing contexts using an implementation specific mechanism.", the [=receiving
user agent=], must send a presentation-connection-open-response message.
Remote Playback Protocol {#remote-playback-protocol}
----------------------------------------------------
This section defines the use of the Open Screen Protocol for starting, terminating,
and controlling remote playback of media as defined by the
[[REMOTE-PLAYBACK|Remote Playback API]]. [[#remote-playback-api]] defines how
APIs in [[REMOTE-PLAYBACK|Remote Playback API]] map to the protocol messages
defined in this section.
For all messages defined in this section, see Appendix A for the full
CDDL definitions.
Issue(123): Add a capability that indicates support for the remote playback protocol.
Issue(148): Make a required/default remote playback state table.
Issue(159): Refinements to Remote Playback protocol.
To learn which receivers are [=compatible remote playback device=]s (also called
available [=remote playback devices=]) for a particular URL or set of URLs, the
controller may send a remote-playback-availability-request message with the
following values:
: urls
:: A list of [=media resources=]. Must not be empty.
Issue(146): Remote Playback HTTP headers.
: headers
:: headers that the receiver should use to fetch the
urls. For example,
[[REMOTE-PLAYBACK#establishing-a-connection-with-a-remote-playback-device|section 6.2.4 of
the Remote Playback API]] says that the Accept-Language header should be
provided.
: watch-duration
:: The period of time that the controller is interested in receiving updates
about their URLs, should the availability change.
: watch-id
:: An identifier the receiver must use when sending updates about URL
availability so that the controller knows which URLs the receiver is referring
to. The controller must choose a value that is unique across all
remote playback availability watches to the same receiver.
In response, the receiver should send a remote-playback-availability-response
message with the following values:
: url-availabilities
:: A list of URL availability states. Each state must correspond to the matching URL
from the request by list index.
The receivers should later (up to the current time plus request
watch-duration) send remote-playback-availability-event messages if
URL availabilities change. Such events contain the following values:
: watch-id
:: The watch-id given in the remote-playback-url-availability-response,
used to refer to the remote playback URLs whose availability has changed.
: url-availabilities
:: A list of URL availability states. Each state must correspond to the URLs from the
request referred to by the watch-id.
Note that these messages are not broadcasted to all controllers. They are sent
individually to controllers that have requested availability for the URLs that
have changed in availability state within the watch duration of the original
availability request.
To save power, the controller may disconnect the QUIC connection and
later reconnect to send availability requests and receive availability
responses and updates. The QUIC connection ID may or may not be the same
when reconnecting. Note that the lifetime of a watch-id is not limited
to one QUIC connection. The receiver must continue sending updates for watches
even if the QUIC connection changes, and thus controller need not send
new URL availability requests if the QUIC connection changes.
To start remote playback, the controller may send a
remote-playback-start-request message to the receiver with the following
values:
: remote-playback-id
:: An identifier that uniquely identifies the remote playback from the
controller to the receiver. It does not need to be unique across all remote
playbacks from that controllers to all receivers nor unique across all remote
playbacks from all controllers to that receivers.
: urls
:: The [=media resources=] that the controller has selected for playback on the
receiver.
: text-track-urls
:: URLs of text tracks associated with the [=media resources=].
: controls
:: Initial controls for modifying the initial state of the remote playback, as
defined in [[#remote-playback-state-and-controls]]. The controller may send
controls that are optional for the receiver to support before it knows the
receiver supports them. If the receiver does not support them, it will
ignore them and the controller will learn that it does not support them from
the remote-playback-start-response message.
Issue(147): Remote playback ID uniqueness.
When the receiver receives a remote-playback-start-request message, it should
send back a remote-playback-start-response message. It should do so quickly,
usually before the [=media resource=] has been loaded and instead give updates
of the progress of loading with remote-playback-state-event messages, unless
the receiver decides to not attempt to load the resource at all. If it chooses
not to, it must respond with the appropriate failure result (such as timeout or
invalid-url). Additionally, the response must include the following:
: state
:: The initial state of the remote playback, as defined in
[[#remote-playback-state-and-controls]].
If the controller wishes to modify the state of the remote playback (for
example, to pause, resume, skip, etc), it may send a
remote-playback-modify-request message with the following values:
: remote-playback-id
:: The ID of the remote playback to be modified.
: controls
:: Updated controls as defined in {#remote-playback-state-and-controls}
When a receiver receives a remote-playback-modify-request it should send a
remote-playback-modify-response message in reply with the following values:
: state
:: The updated state of the remote playback as defined in
[[#remote-playback-state-and-controls]].
When the state of remote playback changes without request for modification from
the controller (such as when the skips or pauses due to user user interaction on
the receiver), the receiver may send a remote-playback-state-event to the
controller.
: remote-playback-id
:: The ID of the remote playback whose state has changed.
: state
:: The updated state of the remote playback, as defined in
[[#remote-playback-state-and-controls]].
To terminate the remote playback, the controller may send a
remote-playback-termination-request message with the following values:
: remote-playback-id
:: The ID of the remote playback to terminate.
: reason
:: The reason the remote playback is being terminated.
When a receiver receives a remote-playback-termination-request, it should
send back a remote-playback-termination-response message to the controller.
If a receiver terminates a remote playback without a request from the controller
to do so, it must send a remote-playback-termination-event message to the
controller with the following values:
: remote-playback-id
:: The ID of the remote playback that was terminated.
: reason
:: The reason the remote playback was terminated.
As mentioned in
[[REMOTE-PLAYBACK#disconnecting-from-a-remote-playback-device|Remote Playback
API section 6.2.7]], terminating the remote playback means the controller is no
longer controlling the remote playback and does not necessarily stop media from
rendering on the receiver. Whether or not the receiver stops rendering media depends
upon the implementation of the receiver.
Remote Playback State and Controls {#remote-playback-state-and-controls}
------------------------------------------------------------------------
In order for the controller and receiver to stay in sync with regards to the
state of the remote playback, the controller may send controls to modify the state
(for example, via the remote-playback-modify-request message) and the receiver
may send updates about state changes (for example, via the
remote-playback-state-event message).
The controls sent by the controller include the following individual control
values, each of which is optional. This allows the controller to change one
control value or many control values at once without having to specify all
control values every time. A non-present control value indicates no change. A
present control value indicates the change defined below. These controls
intentionally mirror settable attributes and methods of the
[HtmlMediaElement](https://html.spec.whatwg.org/multipage/media.html#htmlmediaelement).
: source
:: Change the [=media resource=] URL. See
[HtmlMediaElement.src](https://html.spec.whatwg.org/multipage/media.html#dom-media-src)
for more details. Must not be used in the initial controls of the
remote-playback-start-request message (which already contains a list of URLs).
: preload
:: Set how aggressively to preload media. See
[HtmlMediaElement.preload](https://html.spec.whatwg.org/multipage/media.html#dom-media-preload)