Common Play Framework

Search…
To support a range of Skills that can "play" things, each Common Play Skill must return a confidence score to indicate their ability to successfully complete the users request.
Introduction
Over time, many Skills are likely to use similar keywords - called Intents - to triggers actions. One of the most frequently used keywords is play. This means that several Skills can all use the word play in their Intents - causing something called an intent collision - where Mycroft doesn't know which Skill to invoke because there are so many to choose from.
The Common Play Framework solves this problem by allowing Mycroft to infer a confidence score from an Intent which uses the play keyword. The confidence score is designed so that there is a much higher probability of the right Skill being invoked to handle an Intent which has the keyword play in it.
To take advantage of the Common Play Framework, your Skill needs to be written in a specific way - outlined below:
Basing your Skill on the CommonPlaySkill class instead of MycroftSkill
To interface with the playback control the Skill will be based on the CommonPlaySkill class instead of the normal MycroftSkill. Your Skill also needs to implement two methods, CPS_match_query_phrase and CPS_start.
The setup looks like this:
1
from mycroft.skills.common_play_skill import CommonPlaySkill, CPSMatchLevel
2
​
3
​
4
class TutorialSkill(CommonPlaySkill):
5
    def CPS_match_query_phrase(self, phrase):
6
        """ This method responds wether the skill can play the input phrase.
7
​
8
            The method is invoked by the PlayBackControlSkill.
9
​
10
            Returns: tuple (matched phrase(str),
11
                            match level(CPSMatchLevel),
12
                            optional data(dict))
13
                     or None if no match was found.
14
        """
15
        return None
16
​
17
    def CPS_start(self, phrase, data):
18
        """ Starts playback.
19
​
20
            Called by the playback control skill to start playback if the
21
            skill is selected (has the best match level)
22
        """
23
        pass
24
​
25
​
26
def create_skill():
27
    return TutorialSkill()
Copied!
CPS_match_query_phrase
The argument phrase is sent from the PlaybackControlSkill, and is the entire phrase said by the user with the play keyword stripped out. So if the user says
"Play something by Professor Elemental"
the phrase argument will contain
"something by Professor Elemental"
Using this phrase the Skill Author should now determine if the Skill can play this phrase and return the matched phrase and the confidence level. The confidence level is reported using the CPSMatchLevel enum type.
Possible values are:
CPSMatchLevel.EXACT (The input matches exact)
CPSMatchLevel.MULTI_KEY (The input contains multiple matches such as Artist and Album title)
CPSMatchLevel.TITLE (The phrase contains a matching title)
CPSMatchLevel.ARTIST (The phrase contains a matching artist)
CPSMatchLevel.CATEGORY (The phrase contains a category supported by the skill, Rock, bitpop, Podcast etc.)
CPSMatchLevel.GENERIC (Generic match, maybe contains the skill title but no media match)
where CPSMatchLevel.EXACT is the greatest confidence and the CPSMatchLevel.GENERIC is lowest.
Example:
1
        return (matched_phrase, CPSMatchLevel.TITLE)
Copied!
The method can also return data that will be needed when starting the playback. This is very useful if the skill can play a variety of things of various types. The data is added as a third element in the return tuple and has to be a simple python dict.
Example:
1
        data = {
2
            "track": "my_music.mp3"
3
        }
4
        return (matched_phrase, CPSMatchLevel.TITLE, data)
Copied!
The data is then passed to the CPS_start() method as an argument.
CPS_start
CPS_start simply starts the playback using the data and/or the phrase to determine what to play.
For convenience the self.audioservice object can be used to start playback or queue up tracks.
Example implementation of CommonPlaySkill
Let's fill in the blanks in the the above base and create a Skill to play the best (according to yours truly, @forslund) Commodore 64 remixes!
We add a nice safe data structure to the Skill file:
1
track_dict = {
2
    'bomb jack': 'http://remix.kwed.org/files/RKOfiles/Chronblom%20-%20Bomb%20Jack%20subtune%206%20(violin%20version).mp3',
3
    'druid': 'http://remix.kwed.org/files/RKOfiles/Revel%20Craft%20-%20Druid.mp3',
4
    'crazy comets':  'http://remix.kwed.org/files/RKOfiles/Makke%20-%20Crazy%20Comets%20(Komet%20Non-Stop).mp3',
5
    'boulder dash': 'http://remix.kwed.org/files/RKOfiles/Mahoney%20-%20BoulderDash%20(Commodore%2069%20mix).mp3',
6
    'garfield': 'http://remix.kwed.org/files/RKOfiles/Reyn%20Ouwehand%20-%20Garfield.mp3'
7
}
Copied!
To match from this list the match_one function in mycroft.util.parse can be used to fuzzy match one of the elements in the dict.
First we add the import at the top of the file:
1
from mycroft.util.parse import match_one
Copied!
then we update the CPS_match_query_phrase method to use it to select the best match. This fuzzy matching system will match strings that are close to one of the keys in the above dict. This means phrases like "play crazy comet" will be matched with a fairly high confidence despite not being the exact string in the dictionary.
1
    def CPS_match_query_phrase(self, phrase):
2
        """ This method responds wether the skill can play the input phrase.
3
​
4
            The method is invoked by the PlayBackControlSkill.
5
​
6
            Returns: tuple (matched phrase(str),
7
                            match level(CPSMatchLevel),
8
                            optional data(dict))
9
                     or None if no match was found.
10
        """
11
        # Get match and confidence
12
        match, confidence = match_one(phrase, track_dict)
13
        # If the confidence is high enough return a match
14
        if confidence > 0.5:
15
            return (match, CPSMatchLevel.TITLE, {"track": match})
16
        # Otherwise return None
17
        else:
18
            return None
Copied!
This will include the url of the selected file as "track" in the data received by the CPS_start method.
Which simply becomes
1
    def CPS_start(self, phrase, data):
2
        """ Starts playback.
3
​
4
            Called by the playback control skill to start playback if the
5
            skill is selected (has the best match level)
6
        """
7
        # Retrieve the track url from the data
8
        url = data['track']
9
        self.audioservice.play(url)  # Send url to audioservice to start playback
Copied!
The complete source code can be found here​
Technical Documentation
More information on the Common Play Framework can be found in the Mycroft Technical Documentation.
Where to go for more assistance
Join us in the Skills Mycroft Chat room or join us in the Mycroft Forum.
Fallback Skill
Common Query Framework
Last modified 2yr ago
Copy link
Contents
Introduction
Basing your Skill on the CommonPlaySkill class instead of MycroftSkill
CPS_match_query_phrase
CPS_start
Example implementation of CommonPlaySkill
Technical Documentation
Where to go for more assistance
Introduction

Basing your Skill on the `CommonPlaySkill` class instead of `MycroftSkill`

CPS_match_query_phrase

CPS_start

Example implementation of `CommonPlaySkill`

Technical Documentation

Where to go for more assistance
