Serenade

Getting Started

Welcome to the Serenade docs! Here, you'll find an overview of everything Serenade can do, along with examples. First, let's get Serenade installed on your device.

Installing

Serenade is freely available for macOS, Windows, and Linux. To download Serenade, head to https://serenade.ai/download.

After installation, Serenade will walk you through installing plugins for supported applications, like VS Code, Chrome, and Hyper. Serenade will then guide you through interactive tutorials to practice voice coding.

By default, Serenade uses a cloud-based speech-to-code system. To run Serenade entirely on your device, so no data leaves your computer, check out Serenade Pro.

Using Serenade

Serenade floats above all your other windows, so you can keep it side-by-side with other applications, like your code editor. You can toggle Serenade by clicking the Listening switch or pressing Alt+Space. Then, as you speak, you'll see a list of transcripts in the Serenade window.

Sometimes, Serenade isn't sure what you said, so you'll see a few different options. The first one will be used automatically, but to use a different option (and undo the first one), just say the number you want to use instead. For instance, to use the second option, just say two. If none of the options are right, you can just say undo.

Serenade Basics

As you'll see throughout these docs, most Serenade voice commands have the same form:

<action> <selector>

The action is something you want to do to your code. Common actions include add to add a new line of code, change to edit code, and delete to remove code.

A selector is a block of code to operate on. Some selectors are text-based, like line or word. Even more powerful selectors are code-based, which enable you to reference parts of your code, including function, class, and return value. For a complete list of selectors, see the Reference section.

Serenade commands simply combine an action and a selector: add function hello, change parameter to number, and copy lines five to ten.

You can also chain commands together without pausing. For instance, you can say save focus terminal to save your current file and then focus your terminal, or start of class add method hello to add a new method at the start of a class.

Finally, you can also specify how many times a command should be executed. For instance indent three times will run the indent command three times.

Modes

Serenade has a few different configurable modes to change how your voice commands are interpreted.

Command/Insert Mode

Serenade's default mode is Command Mode. In this mode, if you say something that isn't a valid Serenade command, Serenade will show an x next to the command and won't do anything. To enable command mode, just say command mode.

Sometimes, like when inserting a longer block of text, you want Serenade to simply insert everything you're saying, regardless of whether or not it's a valid command. Serenade's Insert Mode does just that. To enable it, just say insert mode, and then Serenade will insert everything you say. Some commands, likeundo, repeat, andstop listening, will also be presented as alternatives so you don't have to leave dictate mode to use them.

Language Modes

By default, Serenade will auto-detect which programming language is being used based on your editor's filename or active language setting. Sometimes, you might want to override this behavior and specify which language Serenade should use. To do so, simply say python mode, javascript mode, and so on. To get re-enable auto-detection, say auto mode.

Adding Code

Serenade has two different commands for writing code.

insert inserts code right at your cursor, which is helpful for inserting text onto an existing line.
add moves your cursor intelligently based on what you say (e.g., "add parameter"), and is used for writing new statements and larger blocks of code, like functions and classes.

As you'll see, Serenade uses machine learning under the hood to handle many formatting details for you, so you don't have to manually dictate symbols and formatting details like underscores vs. camel case formatting. For instance, if you have a variable foo_bar in scope and you say insert foo bar, Serenade will automatically format your code as foo_bar, so you don't have to specify the underscore.

Insert

The insert command will insert code at the current cursor position.insert is useful for appending text to an existing line of code or inserting text into the middle of a line.

insert commands look like:

insert (above | below)? <code>

Command	Code
insert hello world	`hello world`
insert above one	`one two`

Add

add is used for writing new lines or blocks of code. This command will intelligently position your cursor and handle boilerplate for you. For instance, add parameter foo will move your cursor to the nearest parameter list, and then create a new parameter.

Below are just some examples of add commands—you can use any selector. All add commands have the same form:

add <selector> <code>

Command	Code
add function int factorial	`def factorial() -> int: pass`
add class page	`class Page: pass`
add return say of string hello	`return say("hello")`
add else if x less than three	`if x > 3: return elif x < 3: pass`
add import numpy as np	`import numpy as np`
add argument word brackets zero	`capitalize(word[0])`
add comment fix later	`# fix later`
add decorator app dot route	`@app.route def index(): pass`
add enum colors	`class Colors(enum.Enum): pass`
add if not error	`if (!error) { }`
add callback equals lambda e	`callback = lambda e: pass`
add str method name	`class Person: def name(self) -> str: pass`
add property radius equals three point five	`class Circle: radius = 3.5`
add while i not equal zero	`while i != 0: pass`

Raw Text

system inserts text wherever your cursor has focus, even if no Serenade plugin is present. For instance, you can use system to type into VS Code's "Find" dialog box rather than the main text editor. system also doesn't do much formatting for you, which can be useful if you want to drop down to a lower-level and manually specify all formatting, spacing, etc.

Command	Code
system simple text	`simple text`

Navigating Code

The go to command moves your cursor around the file. With this command, you can jump to any text in your file (e.g., go to random), or any selector (e.g., go to class). Since the go to command is so common, if you just say a selector, like next function or second parameter, Serenade will implicitly use the go to command.

Below are just some examples of go to commands—you can use any selector. All go to commands have the same form:

go to <selector>

Command	Code
go to line two	`def random(low, high): return 4`
go to random	`def random(low, high): return 4`
go to second parameter	`def random(low, high): return 4`
go to start of function	`def random(low, high): return 4`

To move your cursor to the literal text matching a selector name, rather than the selector itself, you can say go to phrase. For instance, you might want to move your cursor to the literal word "parameter" rather than a parameter to a function, so you could say go to phrase parameter. This is similar to how escape works in add and insert commands.

Finally, you can move your cursor by speaking a direction: up,down,left, and right.

Editing Code

In this section, we'll take a look at voice commands you can use for editing existing code, like delete, and change, as well as more powerful refactoring commands.

Deleting

You can delete code with the delete command. Below are just some examples of delete commands—you can use any selector. All delete commands have the same form:

delete <selector>

Command	Code
delete line four	`class Bird: def fly(self): // TODO return`
delete lines three to four	`class Bird: def fly(self): // TODO return`
delete to end of word	`class Bird: def fly(self): // TODO return`

Changing

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

change <selector> to <code>

Command	Code
change argument to string background	`set_color("foreground", "blue")set_color("background", "blue")`
change height to speed	`def fly(height: int): passdef fly(speed: int): pass`
rename class to setup	`class Install: passclass Setup: pass`

You can also copy, cut, and paste code.

Command	Code
copy next two words	`all too well`
cut to end of line	`this is a long line of text`
select previous word	`shake it off`
paste

Refactoring

Serenade supports a variety of commands for refactoring code. All refactoring commands have the same form:

<operation> <selector>

Command	Code
comment function	`# def random(): # return 4`
uncomment lines two to three	`url = "https://serenade.ai" // pages = 3 // download(url, pages)`
indent line	`y = f(x) z = g(y)y = f(x) z = g(y)`
dedent line	`y = f(x) z = g(y)y = f(x) z = g(y)`
duplicate block	`value++ print(value); value++ print(value);`
duplicate function	`def initialize(): buffer.reset() def initialize(): buffer.reset()`
shift line down	`first = "a"; second = "b";second = "b"; first = "a";`
move argument left	`z = f(x, y)z = f(y, x)`
join five lines	`list = [ 1, 2, 3 ]list = [1, 2, 3]`

System Commands

Serenade doesn't just work for applications that have a native Serenade plugin—you can control any application with voice using Serenade. No matter what application you're using, you can use commands like system to insert text, press to press keys (to trigger shortcuts), and focus to switch apps.

Keyboard & Mouse

Command	Description
press enterpress control tabpress command k	Press a key combination
system gmail dot com	Type a string using keystrokes
run makerun npm test	Type a string and press enter
clickleft clickright click	Trigger a mouse click

Application Control

Command	Description
pausestop listening	Pause Serenade
repeat	Repeat the last command
copy	Copy to the clipboard
cut	Cut to the clipboard
paste	Paste from the clipboard
new tabcreate tab	Create a new tab
close tab	Close the active tab
first tabsecond tabtab onetab two	Switch tabs
undo	Trigger an undo
redo	Trigger an redo
focus chromefocus slack	Bring an app to the foreground
launch atomlaunch discord	Launch an app
close terminalclose zoom	Close an app

Editor Integrations

Command	Description
save	Save the current file
style fileformat	Format the current file
open index dot js	Open a file
add breakpoint	Create a breakpoint
remove breakpoint	Remove a breakpoint
toggle breakpoint	Toggle a breakpoint
start debugging	Start a debugger session
stop debugging	Stop the current debugger session
step intostep outstep over	Move the debugger step-by-step
continue	Continue the debugger to the next breakpoint

Dictation Box

Serenade uses a combination of plugins and OS-level accessibility APIs to manipulate text no matter what application you're using. However, some applications don't properly implement accessibility APIs, and so Serenade can't read their text fields. When you're using one of these applications, Serenade will open a dedicated Dication Box, where all Serenade commands will work properly.

The Dictation Box will open automatically when Serenade can't read the current field. You can also say dictation box to open the dictation box yourself. Or, say edit to copy the current text field into the dictation box.

When Dictation Box is open, you can say close to close and and ts contents into the field you were editing. You can also say enter to also press enter after inserting (e.g., for sending a message) or copy to copy the text to the clipboard rather than inserting it.

Command	Description
dictation box	Open an empty dictation box
edit	Open a dictation box with the current text field
copy	Close the dictation box and copy its contents to the clipboard
close	Close the dictation box and paste its contents into the current text field
enter	Same as close, but also press enter afterward

Symbols & Formatting

Serenade's machine learning handles many symbols and formatting details automatically, but you can also manually specify text styles and symbols.

Formatting Text

To specify camel case, underscores, and so on, you can specify a style in any insert, add, etc. command. Below is a list of text styles:

Formatting	Result
lowercase	sing song
camel	singSong
pascal	SingSong
all caps	SING_SONG
underscores	sing_song
snake	sing_song
one word	singsong

When writing code with add and insert, you can specify text styles:

Command	Code
add argument pascal some class	`create(SomeClass)`
insert camel my age equals snake your age plus one	`myAge = your_age + 1`

You can also style existing text by describing a style, followed by a selector to change:

Command	Code
capitalize foo	`fooFoo`
camel case next two words	`one two threeoneTwo three`

Symbols

When speaking any command, you can also include symbols. Here's a list of all of the symbols supported by Serenade:

Transcript	Symbol	Transcript	Symbol	Transcript	Symbol
plus	`+`	dash, minus	`-`	star, times	`*`
slash, divided by	`/`	less than or equal to	`<=`	less than	`<`
greater than or equal to	`>=`	greater than	`>`	not equal	`!=`
double equal	`==`	triple equal	`===`	equal	`=`
left shift	`<<`	right shift	`>>`	and	`&&`
or	`\|\|`	comma	`,`	colon	`:`
dot, period	`.`	underscore	`_`	semicolon	`;`
bang, exclam	`!`	question mark	`?`	tilde	`~`
percent, mod	`%`	at	`@`	dollar	`$`
right arrow	`->`	arrow	`->`	space
backslash	`\`	hash	`#`	caret	`^`
ampersand	`&`	backtick	`	pipe	`\|`
left brace	`{`	right brace	`}`	left bracket	`[`
right bracket	`]`	single quote	`'`	quote, double quote	`"`

You can also enclose text in symbols like braces, brackets, and parens. Here's a list of all of the enclosure symbols supported by Serenade:

Transcript	Symbol	Transcript	Symbol
braces	`{ }`	brackets	`[ ]`
comparators, angle brackets	`< >`	quotes, string	`" "`
single quotes	`' '`	triple quotes	`""" """`
of, parens	`( )`	underscores	`_ _`
double underscores	`__ __`

If you want to use the literal text representation of a symbol (e.g., the word dash rather than the - character, you can escape it by saying escape.

Below are just a few examples of commands using symbols—you can use any of the symbols above.

Command	Code
insert this dot get of key	`this.get(key)`
insert first equals array brackets zero	`first = array[0]`
insert escape plus	`plus`

Tips and Tricks

Instead of worrying about spacing while writing code, use style file once your code is in a reasonable state, and Serenade will automatically format the entire file.
Long insert or add commands can be less accurate than shorter commands. If you're seeing low accuracy, try breaking up longer commands into smaller, separate commands.
The insert and add commands are similar, but have distinct use cases—add works best for writing new lines of code, including larger constructs like functions or classes, while insert works best for inserting or appending text to an existing line.
Use copy/cut, paste, and go to liberally in order to more quickly move code around.
Make sure your system's microphone volume is set to the right level. We've found that around 80%, to make sure the input isn't too loud or too quiet, works best, but try moving it around if Serenade's results aren't accurate.
When using Serenade, try to speak conversationally, as though you were pair programming with someone seated next to you. Over-enunciating words can actually make Serenade less accurate!
If Serenade doesn't know a word, like numpy, you can spell it in a command, as with add import n u m p y.

Reference

This section has a few difference references that you can use as cheat sheets while learning Serenade.

Common Commands

Below is a compact list of commonly-used Serenade commands that you can use as a reference or cheat sheet as you're learning voice coding.

Command	Description	Examples
go to <selector>	Move your cursor around a file	go to line fiftygo to next function
add <code>	Add a new statement or construct	add return falseadd class exception
insert <code>	Insert text at your cursor	insert foo of bar plus baz
change <old> to <new>	Change existing text	change hello to goodbyechange return value to false
delete <selector>	Delete text	delete foo bardelete next function
copy/paste <selector>	Copy, cut, paste	copy methodcut previous two wordspaste
indent/dedent	Change the indentation level of code	indent blockdedent if
save	Save the current file	save
undo	Undo the last operation	undo
open <text>	Open a new file	open react.js
(next \| previous) tab	Switch tabs in your editor	next tabprevious tab
focus <text>	Switch apps	focus codefocus chrome

Code Selectors

Code selectors can be used to describe a block of code you want to reference, like a function, argument, or class. You can use any of these selectors in commands like go to, delete, change, or any command that contains a selector.

The following selectors work for supported languages:

argument list	argument	assert	assignment
assignment value	assignment variable	attribute	attribute value
attribute name	attribute text	body	break
call	case	catch	class
close tag	comment	comment text	condition
constructor	content	continue	debugger
declaration	decorator	default	dictionary
do	do while	element	else if
else	enum	except	export
for	finally	function	generator
getter	if	import	interface
interface list	keyword argument	keyword parameter	key
entry	lambda	list	method
mixin	modifier	modifier list	name
named parameter	named parameter list	namespace	object
open tag	operator	parameter list	parameter value
parameter	parent list	parent	pass
positional parameter	positional parameter list	property	prototype
return	return type	return value	ruleset
set	setter	statement	string
string text	struct	switch	symbol
synchronized	tag	throw	top level statement
tuple	try	type	type alias
using	with	with list	with alias
with item	while	value	vertical

Text Selectors

Text selectors can be used to describe a block of text you want to reference, independent of any programming language. You can use any of these selectors in commands like go to, delete, change, or any command that contains a selector.

The following selectors work in any file, regardless of whether or not Serenade supports the language:

all	block
character	file
letter	line
number	phrase
term	word

Selector Modifiers

Below is a list of common modifiers you can use with any selector above. Modifiers can also be combined (e.g., delete next two words).

Command	Description	Examples
next \| previous	The next or previous instance	next functionprevious class
first \| second \| ...	The index in a list	second parameterfirst word
one \| two \| ...	The index in a list	line fiveargument two
start \| end	The start or end	start of lineend of method
<number> <objects>	Multiple objects at once	three wordsfour functions
X to Y	A range of instances	lines five to tenwords one to three
to start, to end	From the cursor to the start or end	to end of next wordto previous line
<object> <name>	The object with the given name	go to foo barfunction factorialclass dog
phrase	Escaped, literal text	phrase function

FAQ

What macOS permissions does Serenade use?

When Serenade accesses certain features on macOS for the first time, macOS will ask you to grant permission to them. If you've accidentally denied permissions or something is not working as expected, you can check that the proper permissions have been granted.

To find each of these permissions, first open System Preferences, then Security & Privacy, and finally the Privacy tab.

Accessibility: Serenade uses this permission to focus windows for you.
Automation: Serenade uses this permission to press keys for you.
Microphone: Serenade uses this permission to capture speech audio.

What data does Serenade collect?

When you use Serenade Cloud, your audio is streamed to Serenade's cloud-hosted speech-to-code engine and used to improve our models. Source code transformations also happen in our cloud, but we do not save any data from your source code.

When you use Serenade Pro, no audio or source code data is sent to Serenade's servers unless you opt-into sharing audio data to help improve our speech-to-code engine.

How do I fix a "Language not supported" error?

Double-check that your editor has the Serenade plugin installed, and the active file has the correct file extension for the language you're trying to use.

This error could also mean that we don't yet support the code transformation for the language you're using.