This section will cover some very useful - in fact essential - knowledge for getting the most out of your Sonic Pi experience.

We’ll cover how to take advantage of the many keyboard shortcuts available to you, how to share your work and some tips on performing with Sonic Pi.

Sonic Pi is as much an instrument as a coding environment. Shortcuts can therefore make playing Sonic Pi much more efficient and natural - especially when you’re playing live in front of an audience.

Much of Sonic Pi can be controlled through the keyboard. As you gain more familiarity working and performing with Sonic Pi, you’ll likely start using the shortcuts more and more. I personally touch-type (I recommend you consider learning too) and find myself frustrated whenever I need to reach for the mouse as it slows me down. I therefore use all of these shortcuts on a very regular basis!

Therefore, if you learn the shortcuts, you’ll learn to use your keyboard effectively and you’ll be live coding like a pro in no time.

However, don’t try and learn them all at once, just try and remember the ones you use most and then keep adding more to your practice.

Consistency across Platforms

Imagine you’re learning the clarinet. You’d expect all clarinets of all makes to have similar controls and fingerings. If they didn’t, you’d have a tough time switching between different clarinets and you’d be stuck to using just one make.

Unfortunately there are a number of standards for shortcuts with macOS and Windows being two of the major styles and other more esoteric editors such as Emacs offering other approaches. You can choose between these three styles - Mac, Windows | Linux and Emacs Live - using the menu IO -> Shortcut Mode. You can therefore switch between a Windows and a macOS machine and keep your shortcuts consistent.

Customising your Shortcuts

If none of the presets quite fit your fingers, you can build your own. Open Preferences -> Shortcuts and choose the Custom mode. Pick one of the presets as a starting point, then double-click any command and press the key combination you’d like to use - Sonic Pi records it on the spot. Bindings you’ve changed are marked, and if a combination clashes with another command it’s highlighted so you can decide what to do. You can also import and export your custom set, which is handy for sharing it or moving it between machines.

Control and Meta

A key part of the notion of consistency is the naming of shortcuts. In Sonic Pi we use the names Control and Meta to refer to the two main combination keys. On all platforms Control is the same. However, on Linux and Windows, Meta is actually the Alt key while on Mac Meta is the Command key. For consistency we’ll use the term Meta - just remember to map that to the appropriate key on your operating system.

Abbreviations

To help keep things simple and readable, we’ll use the abbreviations C- for Control plus another key and M- for Meta plus another key. For example, if a shortcut requires you to hold down both Meta and r we’ll write that as M-r. The - just means “at the same time as.”

The following are some of the shortcuts I find most useful.

Stopping and starting

Instead of always reaching for the mouse to run your code, you can simply press M-r. Similarly, to stop running code you can press M-s.

Navigation

I’m really lost without the navigation shortcuts. I therefore highly recommend you spend the time to learn them. These shortcuts also work extremely well when you’ve learned to touch type as they use the standard letters rather than requiring you to move your hand to the mouse or the arrow keys on your keyboard.

For example, if you’re in Emacs Live short cut mode, You can move to the beginning of the line with C-a, the end of the line with C-e, up a line with C-p, down a line with C-n, forward a character with C-f, and back a character with C-b. You can even delete all the characters from the cursor to the end of the line with C-k. Other modes will have their own shortcuts which can be easily discovered in the app menu.

Tidy Code

To auto-align your code simply press M-m.

Help System

To toggle the help system you can press M-i. However, a much more useful shortcut to know is C-i which will look up the word underneath the cursor and display the docs if it finds anything. Instant help!

For a full list take a look at section B.2 Shortcut Cheatsheet.

The following is a summary of the main Emacs Live shortcuts available within Sonic Pi. The Mac and Windows | Linux modes differ - switch between them in IO -> Shortcut Mode, or open Preferences -> Shortcuts to view every binding and build your own. Please see Section B.1 for motivation and background.

Conventions

In this list, we use the following conventions (where Meta is one of Alt on Windows/Linux or Cmd on Mac):

• C-a means hold the Control key then press the a key whilst holding them both at the same time, then releasing.
• M-r means hold the Meta key and then press the r key whilst holding them both at the same time, then releasing.
• S-M-z means hold the Shift key, then the Meta key, then finally the z key all at the same time, then releasing.
• C-M-f means hold the Control key, then press Meta key, finally the f key all at the same time, then releasing.
• S-C-a means hold the Shift key, then the Control key, then finally the a key all at the same time, then releasing.

Main Application Manipulation

• M-r - Run code
• M-s - Stop code
• M-i - Toggle Help System
• M-p - Toggle Preferences
• M-{ - Switch buffer to the left
• M-} - Switch buffer to the right
• S-M-0 - Switch to buffer 0
• S-M-1 - Switch to buffer 1
• …
• S-M-9 - Switch to buffer 9
• M-+ - Increase text size of current buffer
• M-- - Decrease text size of current buffer

Selection/Copy/Paste

• M-a - Select all
• M-c - Copy selection to paste buffer
• M-] - Copy selection to paste buffer
• M-x - Cut selection to paste buffer
• C-] - Cut selection to paste buffer
• C-k - Cut to the end of the line
• M-v - Paste from paste buffer to editor
• C-y - Paste from paste buffer to editor
• C-SPACE - Set mark. Navigation will now manipulate highlighted region. Use C-g to escape.
• S-C-a - Select to beginning of line
• S-C-e - Select to end of line
• S-C-Left - Select word to the left
• S-C-Right - Select word to the right
• S-C-Home - Select to beginning of buffer
• S-C-End - Select to end of buffer

Text Manipulation

• M-m - Align all text
• Tab - Align current line or selection (or select autocompletion)
• C-l - Centre editor
• M-/ - Comment/Uncomment current line or selection
• C-t - Transpose/swap characters
• M-u - Convert next word (or selection) to upper case.
• M-l - Convert next word (or selection) to lower case.

Navigation

• C-a - Move to beginning of line
• C-e - Move to end of line
• C-p - Move to previous line
• C-n - Move to next line
• C-f - Move forward one character
• C-b - Move backward one character
• M-f - Move forward one word
• M-b - Move backward one word
• C-M-n - Move line or selection down
• C-M-p - Move line or selection up
• S-M-u - Move up 10 lines
• S-M-d - Move down 10 lines
• M-< - Move to beginning of buffer
• M-> - Move to end of buffer

Deletion

• C-h - Delete previous character
• C-d - Delete next character

Advanced Editor Features

• C-i - Show docs for word under cursor
• M-z - Undo
• S-M-z - Redo
• C-g - Escape
• S-M-f - Toggle fullscreen mode
• S-M-b - Toggle visibility of buttons
• S-M-l - Toggle visibility of log
• S-M-m - Toggle between light/dark modes
• S-M-s - Save contents of buffer to a file
• S-M-o - Load contents of buffer from a file

Sonic Pi is all about sharing and learning with each other.

Once you’ve learned how to code music, sharing your compositions is as simple as sending an email containing your code. Please do share your code with others so they can learn from your work and even use parts in a new mash-up.

If you’re unsure of the best way to share your work with others I recommend putting your code on GitHub and your music on SoundCloud. That way you’ll be able to easily reach a large audience.

Code -> GitHub

GitHub is a site for sharing and working with code. It’s used by professional developers as well as artists for sharing and collaborating with code. The simplest way to share a new piece of code (or even an unfinished piece) is to create a Gist. A Gist is a simple way of uploading your code in a simple way that others can see, copy and share.

Audio -> SoundCloud

Another important way of sharing your work is to record the audio and upload it to SoundCloud. Once you’ve uploaded your piece, other users can comment and discuss your work. I also recommend placing a link to a Gist of your code in the track description.

To record your work, hit the Rec button in the toolbar, and recording starts immediately. Hit Run to start your code if it isn’t already in progress. When you’re done recording, press the flashing Rec button again, and you’ll be prompted to enter a filename. The recording will be saved as a WAV file, which can be edited and converted to MP3 by any number of free programs (try Audacity for instance).

Hope

I encourage you to share your work and really hope that we’ll all teach each other new tricks and moves with Sonic Pi. I’m really excited by what you’ll have to show me.

One of the most exciting aspects of Sonic Pi is that it enables you to use code as a musical instrument. This means that writing code live can now be seen as a new way of performing music.

We call this Live Coding.

Show Your Screen

When you live code I recommend you show your screen to your audience. Otherwise it’s like playing a guitar but hiding your fingers and the strings. When I practice at home I use a Raspberry Pi and a little mini projector on my living room wall. You could use your TV or one of your school/work projectors to give a show. Try it, it’s a lot of fun.

Form a Band

Don’t just play on your own - form a live coding band! It’s a lot of fun jamming with others. One person could do beats, another ambient background, etc. Use the live_audio functionality to combine code with traditional instruments such as a guitar or a microphone.

See what interesting combinations of sounds you can create with code.

TOPLAP

Live coding isn’t completely new - a small number of people have been doing it for a few years now, typically using bespoke systems they’ve built for themselves. A great place to go and find out more about other live coders and systems is TOPLAP.

Algorave

Another great resource for exploring the live coding world is Algorave. Here you can find all about a specific strand of live coding for making music in nightclubs.

Sonic Pi is designed to be fully playable with a screen reader such as VoiceOver, NVDA or JAWS. Everything you need — writing code, running it, reading the documentation, exploring the cards and changing your preferences — can be done from the keyboard, with spoken feedback along the way. This section is a tour of how it all fits together, so you can head straight to the good bits rather than discovering them by accident.

A quick note on names: in Sonic Pi’s shortcut language, Control is the Control key on all platforms, and Meta is Alt on Windows/Linux and Command on Mac. See the section on Using Shortcuts for the full story.

Jumping Around: the Focus Menu

The fastest way to move around Sonic Pi is not to walk the interface element by element but to jump straight to where you want to be. The Focus menu (and its shortcuts) teleports your focus:

• Control-Shift-e — the code editor
• Control-Shift-l — the run log
• Control-Shift-c — the cue log
• Control-Shift-h — the help docs listing (table of contents)
• Control-Shift-d — the help docs details (the page content itself)
• Control-Shift-q — the quickstart cards
• Control-Shift-f — the help logs
• Control-Shift-g — the help debug pane
• Meta-, — the preferences
• Control-Shift-r — the most recent error

You can also cycle through whichever panes are currently visible with F6 (and back again with Shift-F6).

Writing Code

The editor is a standard accessible text area: your screen reader will echo characters and lines as you move and type, and each buffer announces itself by name when you switch to it.

The autocomplete popup is designed to stay out of your way: it never steals focus from the editor, so your typing echo is uninterrupted. When completions are available, press the down arrow to step through them — each one is announced with its name, its category (synth, sample, FX and so on) and its position in the list. Press Return to accept, and the characters that were inserted are read out so you always know the exact spelling. If you’d like the full documentation for the selected completion, press Control-i and it will be spoken in full.

When you run or stop code, that’s announced too. If you’d rather not have “Run” and “Stop” spoken over the start of your music, you can turn just those announcements off with Speak Run and Stop in the Accessibility menu — errors are always spoken.

Reading the Documentation

Open the help system with the Help toggle (or jump straight in with Control-Shift-h). You land in the table of contents: plain up and down arrows move through the chapters, and each page is announced as it loads. Control-Shift-d then places you on the page content itself.

Documentation pages read like a web page: the text carries a real cursor, so the plain arrow keys move through it — left and right by character, up and down by line, with word-by-word movement and Home/End also available. You can re-read or spell out anything, and holding Shift selects as you go for copying. When you reach the end of one paragraph or code block, the cursor flows on to the next, so a whole chapter reads as one continuous document. Headings are exposed as real headings, so your screen reader’s heading navigation can skim from section to section.

If the cursor crosses a link you’ll hear “Link” — press Return to follow it.

Every chapter ends with Previous and Next buttons, and they wrap around: Next from the final chapter returns to the first, so there’s never a dead end. The topic filter box above the table of contents announces how many topics match as you type.

The Cards

The quickstart cards (Control-Shift-q, or Examples → Quickstart Cards…) are small playable snippets of music code. Focus lands directly on the first card, which announces its name, its position in the deck and what it does.

While you’re on a card:

• Space plays or stops the card
• C reads the card’s code aloud
• I inserts the card’s code into your editor at the cursor
• Left and Right arrows move through the deck one card at a time (you’ll hear “First card” or “Last card” at the ends)

Stepping inside a card with your screen reader reads its contents in order: title, code, description, then the Run, Add and Copy buttons.

The Synth and FX Playgrounds

Each synth and FX documentation page opens with a playable instrument: a panel of knobs for its options, a piano you can play with the QWERTY keys (the bottom row a s d f g h j k l are the white notes, with the black notes on the row above), and a code snippet that rewrites itself as you turn the knobs.

The knob panel is a single Tab stop, however many knobs the instrument has. Tab into it and you land on the first knob, which announces its name and value. Then:

• Left and Right arrows move between the knobs
• Up and Down arrows turn the focused knob, with the new value spoken
• Shift with an arrow makes bigger jumps
• Tab moves on past the whole panel to the code snippet

The snippet below the knobs is the code you’d write to get the sound you just dialled in — read it line by line, run it with the Run button, or copy it out. And remember Control-Shift-d jumps straight to the page content from anywhere, so you’re never more than one shortcut from the code.

The Examples

Choosing an example from the Examples menu takes you straight to its code, which reads line by line with the arrow keys just like an editor buffer. Browse Examples in Help… places you in the examples list so you can arrow through them all, with each one loading as you go.

Preferences

The Preferences toggle (or Meta-,) takes you directly into the preferences panel: its tabs, checkboxes and controls all announce their names and states. This is also where you’ll find the audio, look and feel, and accessibility-related options — including visual theme and contrast choices.

If You Get Lost

Focus is never intentionally dropped: opening a pane moves you into it, closing it returns you to the editor, and navigating between documentation pages keeps you on the content. If you do find yourself somewhere unexpected, Control-Shift-e always brings you home to the editor, and F6 walks you through everything currently on screen.

Found something that doesn’t speak, or doesn’t behave as this section promises? That’s a bug — we’d love to hear about it at https://in-thread.sonic-pi.net so we can fix it.