Skip to content

Commit c0d291c

Browse files
terrillterrill
committed
Add more robust playlist support
1 parent ec2d0bc commit c0d291c

23 files changed

Lines changed: 1687 additions & 613 deletions

‎README.md‎

Lines changed: 85 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Able Player
55
the HTML5 `<audio>` or `<video>` element for browsers that support them,
66
and (optionally) the JW Player as a fallback for those that don’t.
77

8-
To see the player in action check our [Able Player Examples][examples] page.
8+
To see the player in action check out the [Able Player Examples][examples] page.
99

1010
Features
1111
--------
@@ -218,7 +218,7 @@ The following attributes are supported on both the `<audio>` and `<video>` eleme
218218
download as much of the media as possible. If the media is not a
219219
central focus, downloading the entire media resource can consume
220220
valuable bandwidth, so preload="metadata" would be a better option.
221-
- **width** - width of the media player in pixels. For video, this value should reflect the target width of the media itself. If not provided will default to 480.
221+
- **width** - width of the media player in pixels. For video, this value should reflect the target width of the media itself. If not provided the player will be sized to fit its container.
222222
- **data-root-path** - define path to root directory of Able Player; generally not required but may be needed in rare instances where Able Player is unable to identify its current path on the web server
223223
- **data-heading-level** - optional; Able Player injects an off-screen HTML heading "Media Player" (or localized equivalent) at the top of the player so screen reader users can easily find the player. It automatically assigns a heading level that is one level deeper than the closest parent heading. This attribute can be used to manually set the heading level, rather than relying on Able Player to assign it automatically. Valid values are 1 through 6. A value of 0 is also supported, and instructs Able Player to not inject a heading at all. The latter should be used only if the web page already includes a heading immediately prior to the media player.
224224
- **data-hide-controls** - optional; set to "true" to hide controls during playback. Controls are visibly hidden but still accessible to assistive technologies. Controls reappear if user presses any key or moves the mouse over the video player region.
@@ -321,10 +321,11 @@ The following attributes are supported on the `<video>` element only:
321321
- **data-youtube-id** - optional; 11-character YouTube ID, to play the YouTube video using *Able Player*.
322322
- **data-youtube-desc-id** - optional; 11-character YouTube ID of the described version of a video. See the section below on *YouTube Support* for additional information.
323323
- **data-youtube-nocookie** - optional; if set to "true" the YouTube video will be embedded using the "youtube-nocookie.com" host.
324-
- **height** - height of the video in pixels. If not provided will
325-
default to 360.
324+
- **height** - height of the video in pixels.
326325
- **poster** - path to an image file. Will be displayed in the player
327326
until the video is played.
327+
328+
If width and height are omitted, the player will be sized to fit its container.
328329

329330
The following additional features are supported by *Able Player*:
330331

@@ -425,9 +426,11 @@ To do so, run the shell script *compile.sh*.
425426
Playlists
426427
---------
427428

428-
An *Able Player* playlist is an HTML list of tracks. The list can be
429-
either ordered (`<ol>`) or unordered (`<ul>`). The following attributes
430-
are supported on the list element:
429+
An *Able Player* playlist is an HTML list of tracks. A playlist can accompany
430+
either a video or audio player, but both audio and video cannot be combined
431+
within a single playlist. The list can be either ordered (`<ol>`) or unordered (`<ul>`).
432+
433+
The following attributes are supported on the list element:
431434

432435
- **class** - required; must be **able-playlist**
433436
- **data-player** - required; must reference the ID of the media
@@ -437,20 +440,86 @@ are supported on the list element:
437440
omitted, the playlist will be external to the player and will appear
438441
wherever you place it on the web page.
439442

440-
Within the playlist, each list item must include data-\* attributes
441-
where \* is the media type and the value of the attribute is the URL
442-
pointing to the media file of that type. For example, the following
443-
audio playlist includes three songs, each of which is available in MP3
444-
and OGG:
443+
Within the playlist, each list item can include the following HTML attributes:
444+
445+
- **data-poster** - path to an image file.
446+
- **width** - width of the video in pixels.
447+
- **height** - height of the video in pixels.
448+
449+
If width and height are omitted, the player will be sized to fit its container.
450+
451+
The following HTML elements must be nested inside each list item:
445452

453+
A `<span>` element with **class="able-source"** for each `<source>` element
454+
that is to accompany the media. When the user selects an item from the playlist,
455+
its able-source `<span>` elements will be copied to `<source>` elements and loaded for playback.
456+
For each attribute that will ultimately be on the media's `<source>` elements,
457+
add the same attributes to each `<span>`, prefaced with **data-**.
458+
459+
460+
Within the playlist, each list item must include the following HTML elements:
461+
462+
- A `<span>` element with **class="able-source"** for each `<source>` element
463+
that is to accompany the media. When the user selects an item from the playlist,
464+
its able-source `<span>` elements will be copied to `<source>` elements and loaded for playback.
465+
For each attribute that will ultimately be on the media's `<source>` elements,
466+
add the same attributes to each `<span>`, prefaced with **data-**.
467+
- A `<span>` element with **class="able-track"** for each `<track>` element
468+
that is to accompany the media. When the user selects an item from the playlist,
469+
its able-track `<span>` elements will be copied to `<track>` elements and loaded for playback.
470+
For each attribute that will ultimately be on the media's `<track>` elements,
471+
add the same attributes to each `<span>`, prefaced with **data-**.
472+
- A `<button>` element with **type="button"**. Inside the button, include either text,
473+
an image, or both. This content would typically be the title of the item. If using an image
474+
alone, be sure to add a meaningful **alt** attribute. If the image is purely decorative and
475+
is accompanied by text, using **alt=""**.
476+
477+
The following example shows a playlist with two videos. The first video has one source (an MP4 file),
478+
and two tracks (captions and descriptions). The second video is hosted on YouTube, and has both a
479+
non-described and described version. It also has a locally-hosted chapters track.
480+
Able Player supports mixed playlists, with videos hosted locally or on YouTube.
481+
446482
```HTML
447-
<ul class="able-playlist" data-player="audio1" data-embedded>
448-
<li data-mp3="song1.mp3" data-ogg="song1.ogg">My First Song</li>
449-
<li data-mp3="song2.mp3" data-ogg="song2.ogg">My Second Song</li>
450-
<li data-mp3="song3.mp3" data-ogg="song3.ogg">My Third Song</li>
483+
<ul class="able-playlist" data-player="my_video_player">
484+
<li data-poster="video1.jpg" data-width="480" data-height="360">
485+
<span class="able-source"
486+
data-type="video/mp4"
487+
data-src="video1.mp4">
488+
</span>
489+
<span class="able-track"
490+
data-kind="captions"
491+
data-src="video1_captions_en.vtt"
492+
data-srclang="en"
493+
data-label="English">
494+
</span>
495+
<span class="able-track"
496+
data-kind="descriptions"
497+
data-src="video1_description_en.vtt"
498+
data-srclang="en"
499+
data-label="English">
500+
</span>
501+
<button type="button">
502+
<img src="video1_thumbnail.jpg" alt="">
503+
Title of Video 1
504+
</button>
505+
</li>
506+
<li data-youtube-id="xxxxxxxxxxx" data-youtube-desc-id="yyyyyyyyyyy">
507+
<span class="able-track"
508+
data-kind="chapters"
509+
data-src="video2_chapters.vtt"
510+
data-srclang="en"
511+
data-label="Chapters">
512+
</span>
513+
<button type="button">
514+
<!-- thumbnail will be retrieved from YouTube -->
515+
Title of Video 2
516+
</button>
517+
</li>
451518
</ul>
452519
```
453520

521+
For additional examples of both audio and video playlists, see the [Able Player Examples][examples] page.
522+
454523
**Supported data-\* audio types:**
455524

456525
- mp3

0 commit comments

Comments
 (0)