Merge pull request #216 from feedbee/shared2

Refactoring of shared.js: plugin-api.js proposal

README.md

@@ -3,8 +3,8 @@ Allows your keyboard media keys (play/pause, next, previous) to work
 when you're listening to music on various streaming websites.
 
 # Supported Sites
+
    * 163 Music
-   * 22tracks
    * 8tracks
    * Amazon Cloud Player
    * Bandcamp
@@ -22,53 +22,60 @@ when you're listening to music on various streaming websites.
    * iloveradio.de
    * Jamstash
    * Jango.com
-   * JB Hi-Fi Now
-   * Livestream.com
    * Mixcloud
-   * Music Choice
+   * Music Choice (untested)
    * Myspace
    * Myzuka.fm
    * Naxos Music Library
    * Netflix
-   * Noon Pacific
+   * Noon Pacific (untested)
    * NRK Radio
    * Ok.ru
-   * Overcast
+   * Overcast (untested)
    * Pandora
    * Phish Tracks
    * Picarto.tv
-   * Plex
+   * Plex (untested)
    * Pocketcasts.com
    * Prostopleer
    * Qobuz
-   * Rdio
    * Relax-Hub.com
    * Saavn.com
    * Slacker
    * Sirius XM Radio
    * SomaFM
-   * Songza
    * Soundcloud
    * Sowndhaus
    * Spotify
    * Spreaker
    * Streamsquid
    * Subsonic (and Madsonic)
-   * Superplayer.fm
-   * Synology Audio Station v.5
+   * Superplayer.fm (untested)
+   * Synology Audio Station v.5 (untested)
    * thesixtyone
-   * Tidal
-   * Tracksflow.com
+   * Tidal (untested)
    * tunein.com
    * Twitch.tv
    * Ustream.tv
    * vk.com (Vkontakte)
+   * XFINITY (untested)
    * Xiami Music
    * YouTube
    * Zvooq
    * Яндекс.Музыка (Yandex.Music)
    * Яндекс.Радио (Yandex.Radio)
 
+# Untested Sites (after latest changes)
+
+   * Music Choice (account is needed)
+   * Noon Pacific (account is needed)
+   * Overcast (account is needed)
+   * Plex (can't simulate click, not working)
+   * Superplayer.fm (regional restrictions)
+   * Synology (special environment is needed)
+   * Tidal (regional restrictions)
+   * XFINITY (account is needed)
+
 # Usage
 
 1. Install extension from the [chrome web store][crx].
@@ -112,8 +119,49 @@ document.addEventListener("MediaNext", function () {
 });
 ```
 
-# Please contribute!
+# Please, contribute!
+
+* Looking for plugins for other music players. Create Pull Requests to contribute. Create Issues to inform us about
+broken sites (but PR is preferable). 
+
+Plugin creation is simple. If you have found a website with media content, that isn't supported by keysocket, just
+write a plugin by yourself and create new Pull Request to share it with others. How to do it?
+
+First of all, determine the fixed part of website's URL, where a media content is shown. In `extension/manifest.json`
+add an item into `content_scripts` array like this:
+
+```
+    {
+      "matches": ["*://example.com/player*"],
+      "js": ["plugin-api.js", "keysocket-example-service-name.js"]
+    },
+```
+
+Create new file into `extension` folder using the pattern `keysocket-example-service-name.js` (use your service name to
+replace `example-service-name` part). Write plugin's code there. Check other plugins for examples.
+
+Typically, plugin can interact with a player using either button press simulation or public API call. The second option
+implies you writing custom JS code to talk to player, while the first one requires just to mention DOM selectors to
+configure keysocket.
+
+```javascript
+keySocket.init('example-service-name', {
+    "play-pause": '...',
+    "prev": '...',
+    "next": '...',
+    "stop": '...'
+});
+```
+
+In the code above two arguments were passed to `keySocket.init` function. The first argument is a plugin name, it used for
+logging and can be anything you want. The second argument is a map used to bind keysocket events (which is caused by
+user pressing control keys) to buttons or code, that handles this event. The events are `play-pause`, `prev`, `next`
+and `stop`. Any of them can be omitted in the map.
+
+So, passing a function as an event handler, you set the code, that will be called when event is thrown. Passing anything
+else, which expected to be a string, you define DOM selector to look up for a DOM object to simulate click on it.
 
-* Looking for adapters for other music players.
+Different websites require different approaches to dial with them. So, make a research to find the best solution in
+your case. Look through the other plugins (`extension/keysocket-*.js` files) for the reference.
 
 [crx]: https://chrome.google.com/webstore/detail/fphfgdknbpakeedbaenojjdcdoajihik

extension/keysocket-163.js

@@ -1,12 +1,9 @@
-function onKeyPress(key) {
-    if (key === NEXT) {
-        var nextButton = document.querySelector('.m-playbar .nxt');
-        simulateClick(nextButton);
-    } else if (key === PLAY) {
-        var playPauseButton = document.querySelector('.m-playbar .ply');
-        simulateClick(playPauseButton);
-    } else if (key === PREV) {
-        var backButton = document.querySelector('.m-playbar .prv');
-        simulateClick(backButton);
+keySocket.init(
+    "163",
+    {
+        "play-pause": ".m-playbar .ply",
+        "prev": ".m-playbar .prv",
+        "next": ".m-playbar .nxt"
+        // stop is omitted
     }
-}
+);

extension/keysocket-amazon-cloud-player.js

@@ -1,12 +1,9 @@
-function onKeyPress(key) {
-    if (key === NEXT) {
-        var nextButton = document.querySelector('.button.icon-fastForward');
-        simulateClick(nextButton);
-    } else if (key === PLAY) {
-        var playPauseButton = document.querySelector(".button.playButton");
-        simulateClick(playPauseButton);
-    } else if (key === PREV) {
-        var backButton = document.querySelector('.button.icon-fastBackward');
-        simulateClick(backButton);
+keySocket.init(
+    "amazon-cloud-player",
+    {
+        "play-pause": ".button.playButton",
+        "prev": ".button.icon-fastBackward",
+        "next": ".button.icon-fastForward"
+        // stop is omitted
     }
-}
+);

extension/keysocket-bandcamp.js

@@ -1,13 +1,9 @@
-var playTarget = '.inline_player .playbutton';
-var nextTarget = '.inline_player .nextbutton';
-var prevTarget = '.inline_player .prevbutton';
-
-function onKeyPress(key) {
-    if (key === PREV) {
-        simulateClick(document.querySelector(prevTarget));
-    } else if (key === NEXT) {
-        simulateClick(document.querySelector(nextTarget));
-    } else if (key === PLAY) {
-        simulateClick(document.querySelector(playTarget));
+keySocket.init(
+    "bandcamp",
+    {
+        "play-pause": ".inline_player .playbutton",
+        "prev": ".inline_player .prevbutton",
+        "next": ".inline_player .nextbutton"
+        // stop is omitted
     }
-}
+);

extension/keysocket-birp.js

@@ -1,12 +1,9 @@
-function onKeyPress(key) {
-    if (key === NEXT) {
-        var nextButton = document.getElementById('fap-next');
-        simulateClick(nextButton);
-    } else if (key === PLAY) {
-        var playPauseButton = document.getElementById('fap-play-pause');
-        simulateClick(playPauseButton);
-    } else if (key === PREV) {
-        var backButton = document.getElementById('fap-previous');
-        simulateClick(backButton);
+keySocket.init(
+    "birp",
+    {
+        "play-pause": "#playbtn",
+        "prev": ".fa-fast-backward",
+        "next": ".fa-fast-forward"
+        // stop is omitted
     }
-}
+);

extension/keysocket-bugs.js

@@ -1,12 +1,9 @@
-function onKeyPress(key) {
-    if (key === NEXT) {
-        var nextButton = document.getElementsByTagName('button')[4];
-        simulateClick(nextButton);
-    } else if (key === PLAY) {
-        var playPauseButton = document.getElementsByTagName('button')[3];
-        simulateClick(playPauseButton);
-    } else if (key === PREV) {
-        var backButton = document.getElementsByTagName('button')[2];
-        simulateClick(backButton);
+keySocket.init(
+    "bugs",
+    {
+        "play-pause": ".btnPlay > button, .btnStop > button",
+        "prev": ".btnPrev > button",
+        "next": ".btnNext > button"
+        // stop is omitted
     }
-}
+);

extension/keysocket-builtin-player.js

@@ -1,12 +1,18 @@
-function onKeyPress(key) {
-    var videoElement = document.getElementsByTagName("video")[0];
-
-    if (key === PLAY) {
-        if (videoElement.paused) {
-            videoElement.play();
-        }
-        else {
-            videoElement.pause();
+keySocket.init(
+    "builtin-player",
+    {
+        "play-pause": function () {
+            var videoElement = document.getElementsByTagName("video")[0];
+
+            if (videoElement.paused) {
+                videoElement.play();
+            }
+            else {
+                videoElement.pause();
+            }
         }
+        // prev is skipped
+        // next is skipped
+        // stop is omitted
     }
-}
+);

extension/keysocket-deezer.js

@@ -1,37 +1,9 @@
-function onKeyPress(key) {
-    if (document.getElementById('player_control_play')) { // old deezer style
-        if (key === NEXT) {
-            var nextButton = document.getElementById('player_control_next');
-            simulateClick(nextButton);
-        } else if (key === PLAY) {
-            var isPlaying = document.getElementById('player_control_play').style.display === 'none';
-            var playPauseButton = null;
-            if (isPlaying) {
-                playPauseButton = document.getElementById('player_control_pause');
-            } else {
-                playPauseButton = document.getElementById('player_control_play');
-            }
-            simulateClick(playPauseButton);
-        } else if (key === PREV) {
-            var backButton = document.getElementById('player_control_prev');
-            simulateClick(backButton);
-        }
-    } else { // new deezer style
-        if (key === NEXT) {
-            var nextButton = document.getElementsByClassName('control-next')[0];
-            simulateClick(nextButton);
-        } else if (key === PLAY) {
-            var isPlaying = document.getElementsByClassName('control-play')[0] ? false : true;
-            var playPauseButton = null;
-            if (isPlaying) {
-                playPauseButton = document.getElementsByClassName('control-pause')[0];
-            } else {
-                playPauseButton = document.getElementsByClassName('control-play')[0];
-            }
-            simulateClick(playPauseButton);
-        } else if (key === PREV) {
-            var backButton = document.getElementsByClassName('control-prev')[0];
-            simulateClick(backButton);
-        }
+keySocket.init(
+    "deezer",
+    {
+        "play-pause": ".control-play, .control-pause",
+        "prev": ".control-prev",
+        "next": ".control-next"
+        // stop is omitted
     }
-}
+);

extension/keysocket-digitallyimported.js

@@ -1,6 +1,9 @@
-function onKeyPress(key) {
-    if (key === PLAY) {
-        var playPauseButton = document.querySelector('#webplayer-region .controls a:first-child');
-        simulateClick(playPauseButton);
+keySocket.init(
+    "digitallyimported",
+    {
+        "play-pause": "#webplayer-region .controls a:first-child"
+        // prev is skipped
+        // next is skipped
+        // stop is omitted
     }
-}
+);