API Reference

class Serenade

Methods to create new Builder objects with either a global scope or scoped to a single application. You can access an instance of this class via the serenade global in any script.

serenade.global()

Create a new Builder with a global scope. Any commands registered with the builder will be valid regardless of which application is focused or language is used.

serenade.app(application)

Create a new Builder scoped to the given application. Any commands registered with the builder will only be valid when the given application is in the foreground.

  • application: Application to scope commands to.

serenade.language(language)

Create a new Builder scoped to the given language. Any commands registered with the builder will only be valid when editing a file of the given language.

  • language: Language to scope commands to.

serenade.scope(applications, languages)

Create a new Builder scoped to the given applications and languages. Any commands registered with the builder will only be valid when one of the given applications is focused and one of the given languages is being used. To specify any application or language, pass an empty list for that parameter.

  • applications: List of applications to scope commands to.
  • languages: List of languages to scope commands to.

class Builder

Methods to register new voice commands.

builder.command(trigger, callback)

Register a new voice command.

  • trigger: Voice trigger for this command.
  • callback: async function to be executed when the specified trigger is heard. Arguments to the async callback are:
    • api: An instance of the API class
    • matched: The matched text. If there's just one slot, matched will be a string, and if there are multiple slots, then matched will be a map from slot names to matched text.

builder.key(trigger, key[, modifiers])

Shortcut for the command method if you just want to map a voice trigger to a keypress. This method is equivalent to:

builder.command("foo", async api => { api.pressKey(key, modifiers); });
  • trigger: Voice trigger for this command.
  • key: Key to press. See Keys below.
  • modifiers: Modifier keys (e.g., "command" or "alt") to hold down when pressing key. See Keys below.

builder.snippet(templated, generated[, transform])

Register a new snippet.

  • templated: A string that specifies the trigger for the voice command. Surrounding text in <> creates a matching slot that matches any text. You can then reference the matched text in the generated snippets, much like regular expression capture groups.

  • generated: A snippet to generate. You can use <> to reference matching slots. You can also define the default formatting for any matching slot by putting a colon after the slot's name; to specify multiple styles, separate them with commands. The default text style is lowercase. Possible values are:

    • caps: All capital letters.
    • capital: The first letter of the first word capitalized.
    • camel: Camel case.
    • condition: The condition of an if, for, while, etc.—symbols like "equals" will automatically become "==". condition implies expression.
    • dashes: Dashes between words.
    • expression: Any expression; symbols will not be escaped, so dash will become -.
    • identifier: The name of a function, class, variable, etc.; symbols will be escaped automatically, so dash will become dash.
    • lowercase: Spaces between words.
    • pascal: Pascal case.
    • underscores: Underscores between words.
  • transform: How to add the snippet to your code. Defaults to statement. Possible values are:

    • argument
    • attribute
    • catch
    • decorator
    • else
    • else_if
    • extends
    • finally
    • method
    • parameter
    • return_value
    • statement
    • tag

builder.text(trigger, text)

Shortcut for the command method if you just want to map a voice trigger to typing a string. This method is equivalent to:

builder.command("foo", async api => { api.typeText(text); });
  • trigger: Voice trigger for this command.
  • text: Text to type.

class API

Methods for workflow automation. An instance of API is passed as the first argument to the callback passed to the command method on a Builder.

api.focus(app)

Bring an application to the foreground.

  • app: Application to focus.

api.pressKey(key[, modifiers)

Press a key, potentially with modifier keys held down.

  • key: Key to press. See Keys below.
  • modifiers: Modifier keys (e.g., "command" or "alt") to hold down when pressing key. See Keys below.

api.runCommand(text)

Execute a Serenade command. For instance, you could run the command next method when you say the word go.

  • text: Text of the Serenade command to run.

api.typeText(text)

Type a string of text.

  • text: Text to type.

api.wait(timeout)

Pause execution for a fixed amount of time.

  • timeout: Amount of time to wait, in milliseconds.

Keys

Here's a list of supported keys you can pass into the pressKey, key, and so on:

  • alt
  • backspace
  • caps
  • command
  • control
  • delete
  • down
  • end
  • escape
  • home
  • left
  • meta
  • option
  • pagedown
  • pageup
  • return
  • right
  • shift
  • space
  • tab
  • up
  • f1
  • f2
  • f3
  • f4
  • f5
  • f6
  • f7
  • f8
  • f9
  • f10
  • f11
  • f12