-
Notifications
You must be signed in to change notification settings - Fork 22
/
api.html
366 lines (338 loc) · 15.8 KB
/
api.html
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
<!DOCTYPE html>
<html lang="en">
<head>
<title>Bullet Chatting API Proposal</title>
<meta charset='utf-8'>
<link rel="stylesheet" href="./local.css" />
<script src='https://www.w3.org/Tools/respec/respec-w3c' async class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "CG-DRAFT",
edDraftURI: "https://w3c.github.io/danmaku/api.html",
shortName: "danmaku",
editors: [{
name: "Zhihao Huang",
companyURL: "https://www.bilibili.com/",
company: "Bilibili Inc."
}, {
name: "Song Xu",
companyURL: 'http://www.migu.cn',
company: "China Mobile"
},{
name: "Fuqiao Xue",
companyURL: "http://www.chinaw3c.org/",
company: "W3C"
}, {
name: "Lei Zhao",
companyURL: "http://www.migu.cn",
company: "China Mobile"
}, {
name: "Zhaoxin Tan",
companyURL: "https://www.bilibili.com/",
company: "Bilibili Inc."
}, {
name: "Yajun Chen",
companyURL: 'http://www.migu.cn',
company: "China Mobile"
}],
wg: "Bullet Chatting Community Group",
wgURI: "https://www.w3.org/community/bullet-chatting/",
github: {
repoURL: "https://github.com/w3c/danmaku",
branch: "main"
},
};
</script>
</head>
<body>
<section id='abstract'>
<p>
This document describes current methods of implementing Danmaku on the Web, and proposes a Web API to easily enable Danmaku in Web browsers.
</p>
</section>
<section id='sotd'>
<p>
This is still a work in progress. The proposal is being incubated in the <a href="https://www.w3.org/community/bullet-chatting/">W3C Bullet Chatting Community Group</a>.
</p>
</section>
<section>
<h2>Terminology</h2>
<p>
This document uses the following terms:
</p>
<ul>
<li>
<dfn>Canvas</dfn> — An element used to draw graphics on a web page. [[2dcontext]]
</li>
<li>
<dfn>WebVTT</dfn> — A file format for marking text tracks. [[webvtt1]]
</li>
</ul>
</section>
<section>
<h2>Current methods of implementing Bullet Chatting</h2>
<p>Currently, Web developers mainly use Canvas or CSS to implement Bullet Chatting.</p>
<section>
<h2>The Canvas Way</h2>
<section>
<h2>Element</h2>
<div>Every bullet chat is a canvas rendering context. For example:</div>
<aside class="example" title="Bullet chat element">
<pre>
const ctx = canvas.getContext('2d');
ctx.fillText('bulletchat', x, y); // x is the x-axis coordinate, and y is the y-axis coordinate
</pre>
</aside>
</section>
<section>
<h2>Style</h2>
<div>Style font (<code>font</code>), color (<code>fillStyle</code>), alpha (<code>globalAlpha</code>) and so on using the properties. For example:</div>
<aside class="example" title="Styling the bullet chat">
<pre>
ctx.font = '20px Arial';
ctx.fillStyle = '#000000';
</pre>
</aside>
</section>
<section>
<h2>Movement</h2>
<div>Every bullet chat needs to be repainted in every frame. Before each change, the developer uses the <code>clearRect</code> method to erase the canvas, calculate the position of the bullet chat in the next frame, and draw the bullet chat in the new position. For example:</div>
<aside class="example" title="Repaint the bullet chat">
<pre>
const text = 'bulletchat'
const bulletList = [{
text,
color: '#ccc',
left: canvas.offsetWidth, // x-axis coordinate
top: getRandomTop(), // y-axis coordinate
offset: getBulletOffset(), // 弹幕移动速度，由canvas实际宽度和移动时间来算出
width: Math.ceil(ctx.measureText(text).width) // 文字像素宽度
}]
function drawBullets() {
for(let index = 0, l = bulletList.length; index < l; i++) {
let bullet = bulletList[index];
let {left, width, top, offset, color, text} = bullet
// 检测弹幕是否超出屏幕
if (left + width <= 0 ) {
bulletList.splice(index, 1);
index--;
continue;
}
// Modify the x-axis coordinate
bullet.left -= bullet.offset
ctx.fillStyle = color;
ctx.fillText(text, left, top);
}
requestAnimationFrame(drawBullets);
}
</pre>
</aside>
</section>
</section>
<section>
<h2>The CSS Way</h2>
<section>
<h2>Element</h2>
<div>Every bullet chat is a <code>div</code> element, i.e., <code><div>danmaku</div></code>.</div>
</section>
<section>
<h2>Style</h2>
<div>Style font (<code>font</code>), color (<code>color</code>), opacity (<code>opacity</code>) and so on using the properties.</div>
</section>
<section>
<h2>Movement</h2>
<div>Take <a href="usecase.html#basic-modes">Rolling Bullet Chatting</a> as an example. The initial position of the bullet chat is in the rightmost, and it moves from right to left under the influence of the two CSS properties, <code>transform</code> and <code>transition</code>:
</div>
<aside class="example" title="">
<pre>
position: absolute;
top: 0;
left: 980px;
transform: translateX(0) translateY(0) translateZ(0);
transition: transform 5s linear;
</pre>
</aside>
<div>Pause: set the <code>transform</code> property of the bullet chatting element to the current position and set the <code>transition</code> duration to 0 to fix the bullet chatting at the current position. For example:</div>
<aside class="example" title="">
<pre>
transform: translateX(-980px) translateY(0) translateZ(0);
transition: transform 0s linear;
</pre>
</aside>
</section>
</section>
<section>
<h2>Advantages and disadvantages of existing implementation methods</h2>
<section>
<h2>The Canvas Way</h2>
<section>
<h2>Advantages</h2>
<p>
The performance is better when used with WebGL and a large number of bullet chatting text can be displayed at the same time.
</p>
</section>
<section>
<h2>Disadvantages</h2>
<p>
Not flexible. It is cumbersome to display bullet chat that contains both text and images, and to pause the animation of one of the moving bullet chats. Moreover, resolution issue needs to be addressed on mobile devices.
</p>
</section>
</section>
<section>
<h2>The CSS Way</h2>
<section>
<h2>Advantages</h2>
<p>
Simple and flexible. Developers can style the bullet chat through the DOM, and supports the combination of images and text. The user can pause a particular bullet chat of interest.
</p>
</section>
<section>
<h2>Disadvantages</h2>
<p>
Huge collections of DOM nodes will be generated when the there are many bullet chats. It will consume more memory and make the page unresponsive. Moreover, to manipulate the bullet chatting such as making the bullet chat disappear, the corresponding DOM node needs to be removed.
</p>
</section>
</section>
</section>
</section>
<section id='proposal'>
<h2>Recommended API</h2>
<p class="note">
The content of this section is still under discussion in the <a href="https://www.w3.org/2011/webtv/">Media and Entertainment Interest Group</a>. If you find any issue, or have any correction or question, feel free to raise a <a href="https://github.com/w3c/danmaku/issues">GitHub issue</a> or send an email to <a href="mailto:[email protected]">[email protected]</a>.
</p>
<section>
<h2>Examples</h2>
<aside class="example" title="Bullet Chatting usage">
<pre>
<bulletchatlist area="100" >
<bulletchat mode="scroll" >This is Content</bulletchat>
<bulletchat mode="bottom" >Fixed Content</bulletchat>
</bulletchatlist>
</pre>
</aside>
<p class="note">
Bullet Chatting uses new elements such as
<code>bulletchatlist</code> and <code>bulletchat</code>. These elements are not used as children of the media elements <code>audio</code> and <code>video</code>. From the Scenarios section, we can see that the usage of bullet chatting is not limited to those media elements like video. In scenarios like Web page interaction or interactive wall, bullet chatting is independent of any media element.
</p>
<p class="note">
This specification describes how the bullet chatting itself is rendered, not including the external bullet chatting list. Since bullet chatting does not depend on <code>video</code>, there is no requirement for a bullet chatting list with timestamps. In a common on-demand video bullet chatting scenario, there is often a list of bullet chatting similar to the time-aligned data in [[webvtt1]], which requires the developer to add <code>bulletchat</code> based on the time offset of the video.
</p>
</section>
<section>
<h2>Elements</h2>
<p>
<code>bulletchatlist</code> is a block-level element, and <code>bulletchat</code> is an inline element. The content permitted as children and descendants of the <code>bulletchat</code> element include: text, images, and hyperlinks.
</p>
</section>
<section>
<h2>Attributes</h2>
<section>
<h2>bulletchatlist element</h2>
<ul>
<li><dfn>area</dfn>: Defines the percentage of the total height of the bulletchatlist in
Bullet Chatting display area, ranging from 0-100, 50 is half screen, 100 is full screen.
The <code>scroll</code> <code>reverse</code> and <code>top</code> Bullet Chatting display
area is calculated from the top of bulletchatlist, the <code>bottom</code> Bullet Chatting
display area is calculated from the bottom of bulletchatlist</li>
<li>
<dfn>allowOverlap</dfn>: Defines whether the Bullet Chatting beyond the display area allows
overlap. <code>false</code> if the display does not show the Bullet Chatting beyond the display
area; <code>true</code> if the Bullet Chatting will be displayed overlapping the display area.
</li>
</ul>
<figure>
<img alt="Example of the area attribute" src="images/sample4.png" width="600">
<figcaption>
When area = 70, the scroll bullet chatting only display in 0-70% height (the blue area)
</figcaption>
</figure>
<figure>
<img alt="Example of the allowOverlap attribute" src="images/sample3.png" width="600">
<figcaption>
In the case of <code>allowOverlap = true; area = 70</code>, when the display area of bullet chatting is not enough, the excess bullet chatting (in green) overlaps the normal ones
</figcaption>
</figure>
</section>
<section>
<h2>bulletchat element</h2>
<ul>
<li>
<code>mode</code>: Defines the type of Bullet Chatting, value is one of the folloing: <code>scroll</code>, <code>top</code>,<code>bottom</code> and <code>reverse</code>.
<p><code>scroll</code> The default value indicates a scroll bullet chat. The bullet chatting scrolls
from left to right, and the scrolling time is controlled by the CSS
property <code>bulletchat-duration</code>. Display time rule: <code>bulletchat</code>the leftmost element
into the <code>bulletchatlist</code> element area to the display <code>bulletchat</code> element from the
rightmost <code>bulletchatlist</code> element of the display region disappears time consumed.</p>
<figure>
<img alt="Scroll bullet chatting" src="images/sample5.png" width="600">
<figcaption>
Bullet chatting scrolling from right to left
</figcaption>
</figure>
<p><code>top</code> indicates the top bullet chatting.</p>
<figure>
<img alt="Top bullet chatting" src="images/sample6.png" width="600">
<figcaption>
Top bullet chatting
</figcaption>
</figure>
<p><code>bottom</code> indicates the bottom bullet chatting.</p>
<figure>
<img alt="Bottom bullet chatting" src="images/sample7.png" width="600">
<figcaption>
Bottom bullet chatting
</figcaption>
</figure>
<p><code>reverse</code> represents a reverse scrolling bullet chatting. The bullet chatting will scroll from
right to left, and the scrolling time is <code>scroll</code> similar.</p>
<figure>
<img alt="Reverse bullet chatting" src="images/sample8.png" width="600">
<figcaption>
Reverse bullet chatting scrolling from left to right
</figcaption>
</figure>
</li>
</ul>
</section>
</section>
<section>
<h2>Events</h2>
<section>
<h2>bulletchat element</h2>
<ul>
<li><code>bulletchatstart</code>: Triggered when the Bullet Chatting animation starts.</li>
<li><code>bulletchatend</code>: Triggered when the Bullet Chatting animation ends.</li>
<li><code>bulletchatcancel</code>: Trigger when the Bullet Chatting is terminated unexpectedly, such as the
Bullet Chatting is removed or hidden, or because the display area is not displayed.</li>
</ul>
</section>
</section>
<section>
<h2>Style</h2>
<section>
<h2>bulletchatlist element</h2>
<ul>
<li><code>bulletchat-play-state</code>: running | paused, defines the state of the Bullet Chatting as running
or paused, and can be inherited.</li>
<li><code>bulletchat-duration</code>: <time>, in seconds (s) or milliseconds (ms), defines the speed of
the Bullet Chatting, which can be inherited.</li>
</ul>
</section>
<section>
<h2>bulletchat element</h2>
<ul>
<li><code>bulletchat-play-state</code>: running | paused, which defines the state of the Bullet Chatting as
running or paused, which can be inherited.</li>
<li><code>bulletchat-duration</code>: <time>, in seconds (s) or milliseconds (ms), defines the speed of
the Bullet Chatting, which can be inherited.</li>
<li><code>bulletchat-delay</code>: <time>, in seconds (s) or milliseconds (ms), defines when the Bullet
Chatting animation begins, defining a negative value allows a Bullet Chatting to start moving from the
middle.
</li>
<li>Font size, color, border, line height, transparency, shadow, etc., same as existing CSS attributes.</li>
</ul>
</section>
</section>
</section>
</body>
</html>