Newlines

The newline command adds a new line at, above, or below the cursor.

[add] newline [above | below]

one
two
three

one
t
wo
three

one
two
three

one

two
three

one
two
three

one
two

three

Changing

The change command selects the nearest match to the cursor and replaces it with some text.

For a complete list of selectors, check out the selectors reference.

change <selector> to <text>

def fly():
    pass

def jump():
    pass

You can also say 'rename' to change the name of a function, variable, class, or other named selector

rename <selector> to <text>

def fly(elevation):
    pass

def fly(height):
    pass

def fly():
    pass

def jump():
    pass

Selecting

You can use commands likecopy, cut, select,paste and duplicate to manipulate text.

For a complete list of selectors, check out the selectors reference.

(copy | cut | select) <selector>

paste [above | below | inline]

Duplicate copies your selection and pastes it above or below your cursor.

duplicate <selector> [above | below]

App Control

You can use Serenade to launch apps, switch windows, and close apps.

launch <text>

focus <text>

close <text>

switch window

(pause | stop listening)

Sending Keystrokes

Serenade can also send keystrokes to any active application, even without a plugin.

press <key>

type <text>

gmail.com

(new | close | next | previous) tab

undo

redo

run

Editor Controls

You can control your editor window with Serenade, which includes opening files and navigating tabs.

save

undo

redo

open <text>

style file

new tab

close tab

(next | previous) tab

tab (one | two | three ...)

(first | second | ...) tab

Debugging

Serenade integrates with the Visual Studio Code debugger, so you can run and debug your code with voice. (Support for IntelliJ and other JetBrains IDEs is coming soon!)

(add | remove | toggle) breakpoint

(start | stop) (debugging | debugger)

step (into | out | over)

continue

inspect <selector>

Chaining

You can chain commands together to avoid having to pause between commands. For example, you can combine the end of file and paste command by saying end of file paste.

Repetition

Serenade supports several different options for repeating commands.

(delete | paste | indent ...) <number> (times | <selectors>)

y = f(x)

    y = f(x)

extraordinary

ordinary

repeat [<text>]

Snippets

Snippets are a powerful way to create shortcuts for code you type regularly. To define new snippets, add them to ~/.serenade/scripts/snippets.js (you may need to create this file if it doesn't exist yet).

Here's an example of a snippet that creates a new Python method whose name is prefixed with test_.

serenade.language("python").snippet(
  "test method <%name%>",
  "def test_<%name%>(self):<%newline%><%indent%>pass",
  { "name": ["identifier", "underscores"] },
  "method"
);

Now, if you say test method foo, the following code will be generated:

def test_foo(self):
    pass

As you can see, the snippet method takes four parameters:

• 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.
• A snippet to generate. If you defined a matching slot called <%name%> in the trigger, then <%name%> in the snippet will be replaced by whatever text was matched in the transcript.
• A map of slots to styles. Styles describe how text should be formatted, and a slot can have multiple styles. For instance, if a slot represents an identifier (e.g., a class name) where symbols aren't allowed, and that identifier should be pascal case, then the values ["identifier", "pascal"] could be used.
  Show possible values

  • caps: All capital letters.
  • capital: The first letter of the first word capitalized.
  • camel: Camel case.
  • dashes: Dashes between words.
  • lowercase: Spaces between words.
  • pascal: Pascal case.
  • underscores: Underscores between words.
  • expression: An expression where symbols are supported. For instance, saying dash will produce -, not dash.
  • identifier: The name of a function, class, variable, etc., where symbols are not supported. For instance, saying foo dash will produce foo_dash, since foo- isn't a valid function, class, etc. name.
  • condition: Similar to expression, but specifically for the condition of an if, for, while, etc. For instance, in a condition, saying equals will produce ==, since that's typical for a condition.
• How to add the snippet to your code. In the above example, we're specifying that this block should be added as a method, so if your cursor is outside of a class, it will move to the nearest class before inserting anything, just as it would if you said "add method". The default value for this argument is statement.
  Show possible values

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

As another example, here's a snippet to add a new React class in a JavaScript file:

serenade.language("javascript").snippet(
  "new component <%name%>",
  "class <%name%><%cursor%> extends React.Component {<%newline%>}",
  { "identifier": ["identifier", "pascal"] }
);

Notice that you can use the special slot <%cursor%> to specify where the cursor will be placed after the snippet. The full list of special slots is:

• <%cursor%>: Where the cursor will be placed after the snippet is added.
• <%indent%>: One additional level of indentation.
• <%newline%>: A newline.
• <%terminator%>: The statement terminator for the current language, often a semicolon.

As one last example, here's a snippet to create a Java class with an extends and implements in one command:

serenade.language("java").snippet(
  "new class <%name%> extends <%extends%> implements <%implements%>",
  "public class <%name%><%cursor%> extends <%extends%> implements <%implements%> {<%newline%>}",
  {
    "name": ["pascal", "identifier"],
    "extends": ["pascal", "identifier"],
    "implements": ["pascal", "identifier"]
  },
  "class"
);

Workflow Automation

You can also use the Serenade API to automate workflows. To define new snippets, use the file ~/.serenade/scripts/custom.js (you may need to create this file if it doesn't exist yet).

For instance, to switch to the terminal and then run the command make clean && make, you can create a custom command that looks like this:

serenade.global().command("make", async api => {
  await api.focus("terminal");
  await api.typeText("make clean && make");
  await api.pressKey("return");
});

The global method specifies that we'd like this command to be triggerable from any application. The command method takes two arguments: the voice trigger for the command, followed by an asynchronous function to execute. An api instance is passed to your async function, which enables you to automate a workflow. Inside of that function, we're using the await keyword to make sure that each operation completes before moving onto the next one. Don't forget to make your function async via the async keyword!

Here's another example that finds text on the current page inside of Chrome when you say a command like find foo:

serenade.app("chrome").command("find <%text%>", async (api, matches) => {
  await api.pressKey("f", ["command"]);
  await api.typeText(matches.text);
});

This time, rather than specifying global(), we used .app("chrome") to make this command valid only when Google Chrome is focused. As with snippets, you can use slots to capture text. In this example, we used a slot called <%text%> to determine what to type into the Chrome search box.

Here's one last example that opens a terminal and then runs two different yarn commands:

serenade.global().command("yarn <%first%> then <%second%>", async (api, matches) => {
  await api.focus("term");
  await api.typeText("yarn " + matches.first);
  await api.pressKey("return");
  await api.wait(3000);
  await api.typeText("yarn " + matches.second);
  await api.pressKey("return");
});

As you can see, when you have multiple slots, the second argument to your callback will be a map, where the keys are the names of your slots, and the values are the matched text.