Version 1.0.
The Web Page Media Control API was created to provide generic way to control web page embedded media content (audio or video). Media Content Source is a web page with any king of media source (sound or video). Media Control Source is one of the folowing: media buttons on the keyboard, hardware buttons on headset, remote control tool or any other hardware or software way to issue media related commands -- Media Actions.
Media Action is an intent to control a media source (to start/stop/pause the playback, or to choose next or previous track, or to change sound volume). Web Page Media Control API described here is used to deliver Media Actions from Browser-Side Component to a web application. Browser-Side Component is a browser itself or an extension that directly binded to Media Control Source. It provides Media Actions to Media Content Source.
Media Events are web page document-level events triggered by Browser-Side Component in response to Media Actions received from Media Control Source. Media Event is a carrier, it holds information about Media Action.
|<-- Web Page Media Control API -->|
___________ _____________ ___________
| Media | | Browser- | | Web |
| Control | --(Media Action)--> | Side | --(Media Events)--> | page |
| Source | | Component | | scripts |
----------- ------------- -----------
Example. Let Media Control Source be keyboard hardware media keys, Browser-Side Component be Keysocket Google Chrome extension (provides support for keyboard media keys). Keysocket uses Web Page Media Control API to send Media Action to web pages by Media Events. Web pages use Web Page Media Control API to receive Media Events and perform Media Action.
The Browser-Side Component triggers following document-level events (Media Events) on Media Actions:
MediaPlayPause
MediaStop
MediaPrev
MediaNext
To receive Media Events, the web page must register itself.
Web pages with embedded Media Content Sources must be registered to be controlled by one or more Browser-Side Components. Web page can be registered/unregistered in two ways: static and dynamic.
Web page can be registered/unregistered statically. Web page must register itselfs by adding <meta name="media-controllable">
tag. This tag must have no content
property, or have content
property value not equal to no
. If the tag is present at the time of Browser-Side Components initialization, page gets registered automatically. Usualy Browser-Side Components initialization occurs after all page scripts are loaded.
Alternatively, web page can be registered/unregistered dynamically. Browser-Side Components listen to MediaControlStateChanged
document-level event on every opened page. When MediaControlStateChanged
event is thrown, Browser-Side Component determines what it should do: register or unregister the web-page.
The agrument of event can be instance of CustomEvent
or Event
. For CustomEvent
detail
property must tell whether to register or unregister the page. If event.detail == "enabled"
the page will be registered. If event.detail == "disabled"
the page will be unregistered. Other values are ignored.
For Event
Browser-Side Component looks for <meta name="media-controllable">
tag on the page. If the tag is found and it's content
attribute is not equal to no
, the page will be registered. To unregister the page, <meta name="media-controllable">
meta tag must be removed, or it's content
attribure must be set to no
: <meta name="media-controllable" content="no">
.
Common part: events handling.
// Wrapper for your plaing source
var player = new MyCustomPlayerImplementation();
// Register for Media Events
document.addEventListener("MediaPlayPause", function () {
player.toggle();
});
document.addEventListener("MediaStop", function () {
player.stop();
});
document.addEventListener("MediaPrev", function () {
player.prev();
});
document.addEventListener("MediaNext", function () {
player.next();
});
Registration. Case A -- Event.
// Register the page to receive user Media Events
addMetaTagToDocumentHead(); // <meta name="media-controllable"> added to html>head inside
document.dispatchEvent(new Event("MediaControlStateChanged"));
Case B -- CustomEvent.
// Register the page to receive user Media Events
document.dispatchEvent(new CustomEvent("MediaControlStateChanged", { "detail": "enabled" }));
Unregistration. Case A -- Event.
// Register the page to receive user Media Events
addMetaTagToDocumentHead(); // <meta name="media-controllable"> added to html>head inside
document.dispatchEvent(new Event("MediaControlStateChanged"));
Case B -- CustomEvent.
// Register the page to receive user Media Events
document.dispatchEvent(new CustomEvent("MediaControlStateChanged", { "detail": "disabled" }));
Browser-Side Component -- browser itself or it's extension -- must:
-
Register a listener for
MediaControlStateChanged
event ondocument
tag into every opened tab on every page load. When the event have been caught, Browser-Side Component determines what it should do: register or unregister the web-page. It acts depending on event argument type.-
If the type is
CustomEvent
, Browser-Side Component must check it'sdetail
property. Ifevent.detail == "enabled"
, the page must be registered. Ifevent.detail == "disabled"
, the page must be unregistered. Other values are ignored. -
If the event agrument is not an instance of
CustomEvent
(so it's an instance ofEvent
), Browser-Side Component must search<meta name="media-controllable">
tags into the page. If one or more tags withcontent
attribute is not equal tono
has been found, the page must be registered. In other case (no tags have been found, orcontent
of at least one tag equal tono
) the page must be unregistered.
-
-
Search for
<meta name="media-controllable">
tag (withoutcontent="no"
attribute) in every tab after every page load. -
Trigger apprioritate Media Event when a Media Action is received. Browser-Side Component use it's own rules to select the page that will receive Media Event. Single page can be selected using Media Focus Stack approach, or all opened pages can receive event, or another logic can be applied.
// Tab registration/unregistration by MediaControlStateChanged event
document.addEventListener("MediaControlStateChanged", function (event) {
if (event instanceof CustomEvent && event.detail) {
if (event.detail === 'enabled') {
registerOrUnregisterPage(true);
} else if (event.detail === 'disabled') {
registerOrUnregisterPage(false);
}
} else {
registerOrUnregisterPage(isPageMediaControllableByTag());
}
});
function isPageMediaControllableByTag() {
var tags = document.getElementsByName("media-controllable");
if (tags.length > 0) {
for (var i = 0; i < tags.length; i++) {
if (tags[i].getAttribute("content") === "no") {
return false;
}
}
return true;
}
return false;
}
function registerOrUnregisterPage(register) {
// operate
}
// Initial tab registration by meta tag
registerOrUnregisterPage(isPageMediaControllableByTag());
- 1.0. May 12, 2017.
CustomEvent
rules added. More examples. - 0.4. May 6, 2015. Meta-tag changed.
- 0.3. May 5, 2015.
MediaControlStateChanged
event is introduced, some terms explained, some new terms introduced. - 0.2. May 1, 2015. Add
MediaControlApiInit
event, add some description. - 0.1. May 1, 2015. Initial version.