System Elements

System elements don't need to be manually defined under the app.json's element property, but can be used in Groups right away. They are used by simply adding their (capitalized) name to a Group.

TIME

The time Element will match any reference to a time.

Return value

Object containing the different time components, as well as a best guess at the referenced time and/or date as a JS date Object. Found times are also listed in the speech.times array.

  • transcript: String. The words indicating the time
  • startWord: Integer. Word array index where the mention of the time starts
  • endWord: Integer. Word array index where the mention of the time starts
  • time:
    • second: Integer, 0-59. Detected mention of or reference to a specific second. False if not detected
    • minute: Integer, 0-59. Detected mention of or reference to a specific minute. False if not detected
    • hour: Integer, 0-59. Detected mention of or reference to a specific second. False if not detected
    • fuzzyHour: Boolean. True if it is fuzzy whether a found mention of an hour is AM or PM. "at 4" would be true while "at 4 in the morning" would result in false
    • day: Integer, 1-31. Detected mention of or reference to a specific second. False if not detected
    • month: Integer, 0-11. Detected mention of or reference to a specific second. False if not detected. January = 0, December = 11
    • year: Integer, YYYY. Detected mention of or reference to a specific second. False if not detected
    • future,past: JS Date object. Best guess of converting the found time information into an actual timestamp. Future is the first possible valid time in the future, past is the most recent possible time in the past. Assuming the current time is 16:05, "at 4" would result in a future timestamp of 04:00 the next morning and a past timestamp of 16:00. If there is enough information to rule out a reference to the past or future, that property will be false ("tomorrow at 4" will always result in past being false for example)

Example

/app.json

"timedReminder": {
    "set": "reminderRegex && TIME",
    "capturingGroup": true
}

When the user says "Remind me in 12 minutes to take the pizza out of the oven":

speech.matches.timedReminder.TIME: { 
    transcript: 'in 12 minutes',
    time:{
        second: 5,
        minute: 6,
        hour: 12,
        fuzzyhour: false,
        day: 14,
        month: 11,
        year: 2016,
        future: '2016-12-14T12:06:05.000Z',
        past: false },
    startWord: 4,
    endWord: 6 
}

LOCATION

Locations can be things such as "Tokyo" or "the gym". Locations are detected by analyzing the grammatical structure of the phrase. Therefore, locations are only detected if the user phrase suggests that a location is being referenced. If a detected location is also a zone, the zone name will not be listed as a location.

Return value

Object containing the location.

  • transcript: String. The words indicating the location
  • startWord: Integer. Word array index where the mention of the location starts
  • endWord: Integer. Word array index where the mention of the location starts

Example

/app.json

"tempAtLocation": {
    "set": "temperatureRegex && LOCATION",
    "capturingGroup": true
}

When the user says "What is the current temperature in the Netherlands":

// speech.matches.tempAtLocation.LOCATION
{
    transcript: 'the netherlands',
    startWord: 4,
    endWord: 5
}

When the user says "I came from New York":

// speech.matches...LOCATION
{
    transcript: 'New York',
    startWord: 3,
    endWord: 4
}

When the user says "New York":

No match, since there is no context indicating that a location is mentioned.

NP

A noun phrase is a group of a noun and its modifiers, such as adjectives or particles. For example, consider the phrase "What is the current temperature". There is one noun in this phrase, "temperature". However, the adjective "current" and particle "the" also relate to this noun. These related words are combined in the NP "the current temperature". This can be useful because it allows you to work with entities mentioned in a phrase instead of individual words.

Verb phrases (VP) and noun phrases (NP) are groups of related words within the user phrase. Such groups are often called "chunks". Each chunk conveys an entity in the phrase and can consist of one or more words.

Returned value

Object containing the chunk.

  • type: NP or VP
  • transcript: String. The chunk transcript
  • startWord: Integer. Word array index where the mention of the chunk starts
  • endWord: Integer. Word array index where the mention of the chunk starts

Example

/app.json

"howMuch": {
    "set": "quantityRegex && NP",
    "capturingGroup": true
}

When the user says "How much brown sugar do I need?":

// speech.chunks
[
    {    
        type: "NP"
        transcript: 'brown sugar',
        startWord: 2,
        endWord: 3
    },
    {
        type: "NP",
        transcript: 'I',
        startWord: 5,
        endWord: 5
    }
]

// speech.matches.howMuch
{
    quantityRegex: {...},
    NP: {
        type: "NP"
        transcript: 'brown sugar',
        startWord: 2,
        endWord: 3
    }
}

VP

A verb phrase is conceptually similar to a NP, except that s VP is centered around a verb instead of a noun. For example, consider the phrase "remind me to go to the gym". This phrase contains three VPs; "remind me", "go to the gym" and a third VP spanning the entire phrase. VPs can be helpful to you because they often describe an action.

If the user phrase is a grammatically correct sentence which is not fragmented or a command, there will technically speaking be a VP which spans the entire user phrase. However, such a VP is excluded for practical reasons.

Example

/app.json

"actionReminder": {
    "set": "timedReminder && VP",
    "capturingGroup": true
}

When the user says: "Remind me in 12 minutes to take the pizza out of the oven":

// speech.chunks
[
    {
        type: "VP",
        transcript: 'remind me',
        startWord: 0,
        endWord: 1
    },
    {
        type: "VP",
        transcript: 'take the pizza out of the oven',
        startWord: 6,
        endWord: 12
    },
    {
        type: "NP",
        transcript: 'I',
        startWord: 5,
        endWord: 5
    }
]

// speech.matches...actionReminder
{
    timedReminder: {...},
    VP: {
        type: "VP",
        transcript: 'take the pizza out of the oven',
        startWord: 6,
        endWord: 12
    }
}