Custom Elements

Custom elements allow you to look for specific characteristics in a user phrase. The type property is required. The available types are string, regex, lemma, pos, device.

string

"type": "string"

Strings are used to match an exact word or phrase.

Input fields

  • value: Required. A string with the word you would like to find. An array of strings is also accepted

Returned value

  • transcript: String. The matched string
  • startWord: Integer. Word array index where the match starts
  • endWord: Integer. Word array index where the match starts

Example

/app.json

"speech": {
    "en": {
        "element": {
            "lightsOn": {
                "type": "string",
                "value": "turn on the light"
            },
            ...

When the user says "Turn on the light in the kitchen":

// speech.matches...lightsOn
{
    transcript: "turn on the light",
    startWord: 0,
    endWord: 3
}

regex

"type": "regex"

Regular expressions are a powerful tool for finding a pattern of characters in a string. In Homey, JavaScript regex patterns are used.

If you are unfamiliar with regex, it may seem daunting at first. However, regex can be incredibly useful for giving your App awesome speech capabilities. Consider writing your regex statements using a website such as https://regex101.com/ to reduce your learning curve.

Notes

  • The ignore case flag "i" will always be applied. This done is because the speech to text engines do not reliably capitalize user phrases at this time.
  • If there are multiple matches in a single user phrase, you will receive the one which matched the most characters while still producing an overall match for the capturing group.

Input fields

  • value: Required. A string which can be interpreted by the JS regex parser. The syntax /{{regex}}/{{flags}} is optional. Any flags will be ignored.

Returned value

  • transcript: String. The matched string
  • startWord: Integer. Word array index where the match starts
  • endWord: Integer. Word array index where the match starts
  • value: Object. The same object returned by {{user phrase}}.match(/regex/i);.

Example

/app.json

"speech": {
    "en": {
        "element": {
            "dimWords": {
                "type": "regex",
                "value": "(?:(lower|dim|(turn\\s)?down|decrease)|(raise|increase|boost|(turn\\s)?up))"
            },
            ...

When the user says "Turn down the lights in the kitchen":

// speech.matches...dimWOrds
[
    'turn down',
    'turn down',
    'turn ',
    index: 0,
    input: 'turn down the lights'
]

device

"type": "device"

It's convenient for a user to refer to a device by name. If it makes sense for a user to mention a device by name, you can specify that properties that device must have in order to be relevant to a particular group.

Input fields

  • value: Required. An object where you can specify the properties of devices which are be relevant to an action. More information about device properties to filter can be found in Drivers. Any matching devices will be made available to you in the speech object.

Returned value

  • transcript: String. The matched string
  • startWord: Integer. Word array index where the match starts
  • endWord: Integer. Word array index where the match starts
  • value: Object. The same object that was generated during pairing

Example

/app.json

"speech": {
    "en": {
        "element": {
            "onOffLight": {
                "type": "device",
                "value": {
                    "class": "light",
                    "online": true,
                    "available": true,
                    "capabilities": ["onoff"]
                }
            },

When the user says "Turn off the ceiling lamp":

// speech.matches...onOffLight
Device

pos

"type": "pos"

Part-of-speech(pos) tags are used to put a word in a certain category based on its use and function in a phrase. A basic introduction of pos tags can be found here. In Homey pos tags can be used to indicate that you expect a certain grammatical structure or to specify that a specific word should only match your App when it is used with a particular grammatical function.

To make the use of pos tags easier for developers, a set of pos tags is used which is generalized across languages, known as the Universal Dependencies tagset.

Input fields

  • value: Required. Object containing the following properties:
    • pos: Required. An uppercase string with the pos tag you would like to find.
    • string: Optional. A string with the word you would like to find that also has the specified pos tag.
    • regex: Optional. A string which can be interpreted by the JS regex parser. The regex statement should not contain spaces. If this matched word also has the specified pos tag it will produce a match. The syntax /{{regex}}/{{flags}} is optional. Flags will be ignored.

Returned value

  • transcript: String. The matched text. If a regex was specified which matches part of the word, only that part is returned.
  • startWord: Integer. Word array index where the match starts
  • endWord: Integer. Word array index where the match starts

Example

/app.json

"speech": {
    "en": {
        "element": {
            "lightPos": {
                "type": "pos",
                "value": {
                    "pos": "NOUN",
                    "regex": "(light|lamp)"
                }
            },

When the user says "Turn down the lights in the kitchen":

// speech.matches...lightPos
{
    transcript: "light",
    startWord: 3,
    endWord: 3,
}