Warning, /plasma/plasma-bigscreen/documentation/README.md is written in an unsupported language. File is not indexed.
0001 ## Plasma-Bigscreen Voice Application Development Guidelines 0002 0003 - [Plasma-Bigscreen Voice Application Development Guidelines](#plasma-bigscreen-voice-application-development-guidelines) 0004 - [Abstract](#abstract) 0005 - [Developing a skill for Mycroft AI](#developing-a-skill-for-mycroft-ai) 0006 - [Skill Structure](#skill-structure) 0007 - [Skill Sample ___init_ __.py file](#skill-sample-init-py-file) 0008 - [Adding a Graphical User Interface to the skill](#adding-a-graphical-user-interface-to-the-skill) 0009 - [Skill Sample example.qml file](#skill-sample-exampleqml-file) 0010 - [Converting a GUI Skill to a Voice Application](#converting-a-gui-skill-to-a-voice-application) 0011 - [Creating an entry point / homepage for your GUI skill](#creating-an-entry-point--homepage-for-your-gui-skill) 0012 - [Creating a desktop file for your skill](#creating-a-desktop-file-for-your-skill) 0013 - [Adding your Voice Application to the Mycroft Skill Installer](#adding-your-voice-application-to-the-mycroft-skill-installer) 0014 - [The "skill.json" file](#the-%22skilljson%22-file) 0015 - [Adding you application to the Pling Store](#adding-you-application-to-the-pling-store) 0016 0017 ### Abstract 0018 0019 All Voice Applications for Mycroft AI, start out as simple voice skills with a graphical user interface. This documentation will provide you with all the basics of creating new voice applications and also converting your exsisting voice skills or gui skills to complete voice applications. 0020 0021 This tutorial requires Mycroft-Core, Mycroft-GUI and Mycroft-Skill-Installer. We are in this tutorial going to create a graphic user interface skill for Mycroft-AI which can be installed as a Voice Applications on the Plasma Bigscreen Platform. 0022 0023 ### Developing a skill for Mycroft AI 0024 0025 Skills for Mycroft are written using the Python programming language. Creating a skill requires at least basic python experience, a mycroft installation or device, and an idea of what your skill will do, and how people will use it. 0026 0027 We will showcase a simple hello-world example skill below. 0028 0029 #### Skill Structure 0030 0031 - “myexampleskill” should be replaced with name of your skill 0032 - “authorname” should be replaced with your git repository username 0033 0034 Your directory structure should now be as follows: 0035 0036 ``` myexampleskill.authorname/__init__.py 0037 myexampleskill.authorname/requirements.txt 0038 myexampleskill.authorname/dialog/en-us/example-speak.dialog 0039 myexampleskill.authorname/vocab/en-us/example-one.voc 0040 myexampleskill.authorname/ui/example.qml 0041 myexampleskill.authorname/res/desktop/myexampleskill.desktop 0042 myexampleskill.authorname/res/desktop/myexampleskill_icon.png 0043 myexampleskill.authorname/res/desktop/skill.json 0044 ``` 0045 0046 #### Skill Sample ___init_ __.py file 0047 This file is where most of the Skill is defined using Python code. This file will be referenced through out this tutorial as we move along different sections of this tutorial. 0048 0049 To learn more in-depth about concepts of Vocab, Dialogs and creating Mycroft AI skills refer to: https://mycroft-ai.gitbook.io/docs/skill-development/introduction 0050 0051 ``` 0052 import sys 0053 from adapt.intent import IntentBuilder 0054 from mycroft import MycroftSkill, intent_handler 0055 0056 class MyExampleSkill(MycroftSkill): 0057 0058 def __init__(self): 0059 super().__init__("MyExampleSkill") 0060 0061 def initialize(self): 0062 self.add_event('myexampleskill.authorname.home', self.homepage) 0063 self.gui.register_handler("ExampleSkill.ButtonClicked", self.handleButtonClick) 0064 0065 def homepage(self): 0066 self.gui['exampleText'] = "Hello World" 0067 self.gui.show_page("example.qml") 0068 self.speak("Welcome To Hello World") 0069 0070 @intent_handler('handle_example_helloWorld').require('example-one') 0071 def handle_example_helloWorld(self, message): 0072 self.gui['exampleText'] = "Hello World" 0073 self.gui.show_page("example.qml") 0074 self.speak("Welcome To Hello World") 0075 0076 def handleButtonClick(self): 0077 self.speak_dialog("example-speak") 0078 0079 def stop(self): 0080 pass 0081 0082 def create_skill(): 0083 return MyExampleSkill() 0084 ``` 0085 0086 ### Adding a Graphical User Interface to the skill 0087 0088 Skill Graphical User Interfaces are written using QML user interface markup language. 0089 0090 #### Skill Sample example.qml file 0091 0092 This file is where one can design the UI for the skill, the skill can have multiple pages or a single page to display. 0093 0094 - A skill page can be called from the Mycroft Skill with ***self.gui.show_page(*pagename*)*** where *pagename* is replaced by the page that you want to display 0095 - Skill page can be provided data from the skill with ***self.gui['exampleText'] = 'Hello World'*** where *exampleText* key, value is replaced by the data you want to show on your skill page 0096 0097 For more in-depth tutorial on creating skill graphical user interfaces, understanding Mycroft-GUI modules, available delegates and more detailed examples refer to: https://mycroft-ai.gitbook.io/docs/skill-development/displaying-information/mycroft-gui 0098 0099 ``` 0100 import Mycroft 1.0 as Mycroft 0101 0102 Mycroft.Delegate { 0103 0104 ColumnLayout { 0105 anchors.fill: parent 0106 0107 Label { 0108 id: labelId 0109 Layout.fillWidth: true 0110 Layout.preferredHeight: Kirigami.Units.gridUnit * 4 0111 text: sessionData.exampleText 0112 } 0113 0114 Button { 0115 id: buttonExample 0116 Layout.fillWidth: true 0117 Layout.preferredHeight: Kirigami.Units.gridUnit * 2 0118 text: "Speak" 0119 onClicked: triggerGuiEvent("ExampleSkill.ButtonClicked", {}) 0120 } 0121 } 0122 } 0123 ``` 0124 ### Converting a GUI Skill to a Voice Application 0125 0126 Mycroft voice skills with a GUI can easily be converted to a Voice Application by adding the following to your skill: 0127 0128 - A homepage entry point: a main page to the skill that can show an inital page of the skill or list of voice commands a skill can use for example when the voice application is started 0129 0130 - Desktop File: defines the skill as an voice application with an entry point 0131 0132 ``` 0133 myexampleskill.authorname/res/desktop/myexampleskill.desktop 0134 ``` 0135 - Voice Application Icon: icon for the voice application 0136 0137 ``` 0138 myexampleskill.authorname/res/desktop/myexampleskill_icon.png 0139 ``` 0140 - Skill.json: required for uploading to the store and making the voice application available to the skill installer 0141 ``` 0142 myexampleskill.authorname/res/desktop/skill.json 0143 ``` 0144 0145 #### Creating an entry point / homepage for your GUI skill 0146 0147 Homepage for skills is the starting point of an voice application, In the example below we see the corresponding function defined in the __init_ _.py file that is called when the application is opened. 0148 0149 *part of the __init_ _.py example above* 0150 0151 ``` 0152 def initialize(self): 0153 ### 0154 - Adding an event to the skill to display the homepage when start voice application event is sent by mycroft-gui 0155 - The start event will always be called "yourskillname.authorname.home" 0156 - In this example the event is liked to a function defined: self.homepage 0157 ### 0158 0159 self.add_event('myexampleskill.authorname.home', self.homepage) 0160 ... 0161 0162 def homepage(self): 0163 ### 0164 - Function called when asked to display homepage 0165 - Sends sample data 'exampleText' to hompage 0166 - Shows the 'example.qml' file as the homapage 0167 - Speaks the welcome message 0168 ### 0169 0170 self.gui['exampleText'] = "Hello World" 0171 self.gui.show_page("example.qml") 0172 self.speak("Welcome To Hello World") 0173 0174 ``` 0175 0176 #### Creating a desktop file for your skill 0177 0178 The desktop file provides the application launcher with all the information about the voice application, it also defines the starting entry point of the skill. 0179 0180 The desktop file can be customized as per the skill authour / application developers requirements, but the desktop file must contain the following keys and values for the voice application to launch correctly: 0181 0182 - Exec: This contains how the voice application will be executed, All voice applications are executed inside of the Mycroft GUI skillview and hence are required to start using the following exec: 0183 0184 ``` 0185 Exec=mycroft-gui-app --hideTextInput --skill=myexampleskill.authorname.home 0186 ``` 0187 - Categories: This contains the application category the voice application is part of, to display it correctly under the voice applications section, the value of this category must be set to: 0188 0189 ``` 0190 Categories=VoiceApp 0191 ``` 0192 0193 - StartupNotify: As the voice application is started inside the mycroft-gui skill view the generic desktop version of startup notifications do no work with voice applications and hence must always be disabled or set to false to avoid empty windows from being created 0194 0195 A Complete example of how a desktop file must be formatted for the voice application: 0196 0197 ``` 0198 [Desktop Entry] 0199 Terminal=false 0200 Type=Application 0201 Name=MyExampleSkill 0202 Exec=mycroft-gui-app --hideTextInput --skill=myexampleskill.authorname.home 0203 Icon=myexampleskill_icon 0204 Categories=VoiceApp 0205 StartupNotify=false 0206 X-DBUS-StartupType=None 0207 X-KDE-StartupNotify=false 0208 ``` 0209 0210 ### Adding your Voice Application to the Mycroft Skill Installer 0211 0212 Voice Applications currently can only be installed using the Mycroft Skill Installer, the Mycroft Skill Installer requires the Voice Application to be uploaded to the Pling Store and also to a git repository in order to be available inside the installer. 0213 0214 #### The "skill.json" file 0215 0216 Let's look at an example skill.json file required to be uploaded to the "Files" section in the add product page of the pling store: 0217 0218 ``` 0219 { 0220 "name": "Youtube Skill", 0221 "skillname": "youtube-skill", 0222 "authorname": "aiix", 0223 "foldername": "", 0224 "url": "https://github.com/AIIX/youtube-skill", 0225 "branch": "master", 0226 "desktopFile": true, 0227 "warning": "", 0228 "examples": [ 0229 "Youtube metallica", 0230 "Youtube paradise city by guns and roses", 0231 "Pause youtube", 0232 "Resume youtube" 0233 ] 0234 } 0235 ``` 0236 0237 - **name (Value Required)**: The name of the skill as it would show up on the skill installer 0238 - **skillname (Value Required)**: The name of the skill folder which should match the skill name 0239 - **authurname (Value Required)**: The username of the author where the skill repository is uploaded 0240 - **foldername (Value Optional)**: The foldername of an orignal mycroft skill that the current skill is replacing (this is required only when replacing a default skill installed by mycroft for example your weather skill replacing the mycroft-weather.mycroftai skill) 0241 - **url (Value Required)**: The git repository url where the skill is uploaded 0242 - **branch (Value Required)**: The branch inside the git repositry for checkout 0243 - **desktopFile (Value Required)**: This value must be set as true if this voice application is to be displayed under voice applications, it can also be set to false for voice based mycroft skills that aren't complete voice applications 0244 - **warning (Value Optional)**: provides a message to the user incase the author decides to mark the skill as unstable or work in progress 0245 - **examples (Value Required)**: This field populates the voice commands of the skill / voice application inside the Mycroft Skill Installer 0246 0247 #### Adding you application to the Pling Store 0248 0249 The Pling Store is a publishing platform for open source applications, addons, wallpapers, applets and more. The Mycroft Skill Installer leverages the infrastructure provided by the pling store to make installing voice applications a breeze. 0250 0251 - Create an account on https://www.pling.com/ 0252 - Start by adding a new product: 0253 0254 <img src="images/addproduct.png" 0255 style="float: center; margin-left: 10px; width: 500px" /> 0256 0257 - Under add products, fill out the following required information: 0258 - Product Name: The name of your voice application as you would like it to appear on the Mycroft Skills Installer 0259 - Category: App Addons 0260 - Sub Category: Mycroft Skills 0261 - Sub Category: Can be a selection from Configuration, Entertainment, Information, Productivity 0262 - Product Descriptiton: A short description on what the voice application/skill does 0263 - Link to Source/Code: Link to the git repository where the application/skill have been uploaded 0264 - License: Select the license the code is available under 0265 - Logo: An image icon representing your skill 0266 0267 <img src="images/addproductinformation.png" 0268 style="float: center; margin-left: 10px; width: 1900px" /> 0269 0270 - Upload the skill.json file under Files in the add product page 0271 0272 <img src="images/addproductskilljson.png" 0273 style="float: center; margin-left: 10px; width: 1900px" /> 0274 0275 - Save the added product 0276 0277 The voice application should show up under the Mycroft Skill Installer as soon as the server has finished updating, ETA: ~60 minutes