How to use Soundboy

Install and first run

1. Download it

   From the download section: Apple Silicon or Intel for a Mac (macOS 12 or later), or Windows 10 or later. Not sure which Mac you have? Apple menu ▸ About This Mac: an “Apple M” chip means Apple Silicon.

2. Open it

   The Mac version is signed and notarised, so it opens with a double-click. The Windows version isn’t code-signed yet: SmartScreen warns once, so choose More info, then Run anyway.

3. Tell it where downloads land

   Three welcome cards come first. The second asks which folder your downloads land in: usually Downloads, or your record pool app’s download folder. Choosing it there is what gives Soundboy permission to read it, and nothing is read until you finish the cards.

4. Start the free month

   Next, enter your email and choose Start the month. The month runs from then, not from the download, and everything is switched on. Closed it by mistake? Start your free month is at the bottom of the window.

5. Give the number keys folders

   Press a number with no folder behind it and a folder picker opens. The key is named after the folder you pick, and the track on screen is filed there. To set a key without filing anything, click it instead. Fill as many as you like, and add more later.

That’s the setup. The first track loads but doesn’t play: opening the app shouldn’t put sound in the room. Press Space to begin.

To sort a different folder later, choose Crate ▸ Change Source Folder…, click Add a crate… in the sidebar, or use Settings ▸ Folders (⌘,). Clicking the crate’s name at the top of the window opens Settings too.

The loop

The whole app is one loop: hear it, file it, next.

1. A track plays

   It starts 30% of the way in, because intros tell you nothing. With Skip the breakdown on (the default), it checks that point and moves it if it would land in a quiet section.

2. You listen

   For as long as you need. The waveform is coloured by frequency, so you can see the drop before you reach it. Click it to jump. → and ← jump 15 seconds, and with ⇧ they jump 30.

3. You press a number

   The track goes into that folder and the next one plays straight away. It was loaded while you listened.

4. Not sure?

   M sends it to Maybe, S skips it and leaves it where it is, and ⌫ moves it to the Soundboy Trash. ⌘Z takes back a Maybe or a Trash. A skip moves nothing, and ⇧S goes back through the tracks you skipped.

You never wait on the disk. The queue moves on when you press the key, and the file is moved in the background. If a move fails, the track goes back in the queue and the status line says why.

What’s on screen

In 0.7.0 the window has a new look, Studio. It follows your Mac, light or dark, and has the Mac’s own red, yellow and green window buttons. The original look, Deck, and Nineties are in Settings ▸ Window ▸ Skin. If you were on Deck before you updated, you’re on Studio now: choose Deck there to go back. The Mac screenshots on this page were taken in Deck, before 0.7.0.

• Title strip. The Mac’s window buttons, then the name of the crate you’re sorting, with where it lives beside it. Click the name to open Settings. On the right are three switches: Purge for Purge mode in this folder, Mic for voice mode, and On top to keep the window floating above other windows. Double-click the strip to fill the screen. On Windows the strip has its own window buttons, and no Mic.
• Sidebar, new in 0.7.0. Crates are the folders you’ve sorted lately, the open one first with how many are left: click one to switch, or Add a crate… for another. Filed has Maybe and Soundboy Trash, which open in Finder when you’re sorting this Mac, and on dropbox.com when you’re sorting Dropbox. Pad sets are your profiles, when you have more than one. Pace appears once there is one. The button at the left of the title strip, or ⌃⌘S, hides and shows it, and the window widens to make room when it comes back. It also folds away when the window is too narrow for it. Settings ▸ Window ▸ Sidebar and Window ▸ Sidebar do the same.
• Now Auditioning. Title and artist from the tags, or the filename if there are none. BPM, key in both notations (like Am 8A), genre, format, size and bit rate. A Dupe? badge names the folder that already holds a copy, and which cut it is. Click it to show that file in Finder. On the right: where you are in the crate, how many are left, and your pace.
• Waveform. Warm colours are bass and cool colours are treble. The part already played is dimmed. Click anywhere to jump.
• Transport row. Previous and next track either side of play, and ↻ for Continuous play. Then Maybe, Skip, Folders for the folder shelf, and Trash. The volume is on the right: click or drag across the bars, or scroll over them.
• Queue. Every track in the folder, oldest download first. Filed tracks stay in the list, crossed out and labelled with where they went, so undo has somewhere to land. The columns are Track, Artist (new in 0.7.0), BPM, Key, Album, Genre, Filed to and Size. With Artist showing, Track leaves off the artist’s name at the front. Click a heading to sort, again to reverse, and a third time for the order the files arrived in. Drag a heading to move it, or its edge to resize it. ⌘F filters by name, artist, album or genre, and the box shows a green ring while it has your typing.
• Keys. The ten folders on the number keys, with how many you’ve filed to each this session, and the page tabs. On the left, Copy or Move says what a bare number does, beside the profile picker. A lit key is a suggestion, and the line above the keys says why (see Suggestions).
• Status line. What just happened, with an Undo button that names where the last track went, and ? for the cheat sheet. With voice mode on, it shows what it heard. When an update has downloaded, it says so.

Every key

Press ? in the app for the same list. While the cheat sheet or Settings is open, filing keys do nothing, so a stray 4 can’t file a track you can’t see.

Filing

Playing

Getting around

With the window in the background

For a Stream Deck, a macro pad or Keyboard Maestro. Turn on Work without focusing the window in Settings ▸ Remotes (it’s on by default). Most keyboards can’t type these keys, so no other app loses a shortcut.

Filing

Copy or move

Settings ▸ Keys ▸ What a number key does. Copy leaves the original where it was, and new installs start on Copy. Move takes it out of the download folder. The Copy or Move label beside the keys says which, and the key numbers are tinted to match: blue for copy, amber for move. ⌘ with a number copies and ⌥ with a number moves, for just that track, whatever the setting.

Pages and profiles

A page is the next ten folders in the same setup. There can be up to six. Add one with the + beside the page tabs, and switch with ⇧1–⇧6.

A profile is a whole different setup, such as Weddings, Club or Latin Night, each with its own keys, pages and Maybe folder. Switch with ⌘P, the picker beside the keys, or Pad sets in the sidebar. Duplicate a profile in Settings ▸ Keys to start a new one from a working set. The duplicate check looks in your library folders and in the folders on the profile you’re in.

Several tracks at once

Shift-click a track in the queue to select everything from the playing track to that one. The next number key, M or ⌫ acts on all of them (K too, in Purge mode), and one ⌘Z takes them all back. Esc clears the selection.

Maybe and Trash

M sends a track to your Maybe folder: set it in Settings ▸ Keys, or pick one the first time you press M. ⌫ moves it to Soundboy Trash in your home folder, or to /Soundboy Trash at the top of your Dropbox. It’s never deleted: it’s an ordinary folder you can open, empty or pull files out of whenever you like. ⌘Z brings a trashed track back. On this Mac, the sidebar opens both folders in Finder.

Undo

⌘Z reverses the last action: a moved or trashed file goes back where it was, and a copy goes to the Mac’s own Trash. It remembers the last fifty, and ⌘⇧Z redoes. If something else has taken the file’s old name since, undo stops and tells you rather than overwrite it. A copy you’ve changed since is left alone.

When the name is already taken

A move to another drive is copied, checked, and only then removed from the download folder.

Suggestions and the auto page

A key lights when the track very probably goes there. Soundboy learns that from everything you file: the artist and any remixer, the folder the track came from, its genre, the record pool’s pack, its tempo, where the last track went, and where another cut of the same song went. The line above the keys says why, like House — DJ Snake · 3 of 3 went here. Return files into the lit key. When nothing is that likely, the likeliest keys get a small dot instead, and a page tab gets one when a likely key is on another page.

Trashed before marks a file a pool has sent again after you trashed it, and Likely trash a track like the ones you usually bin, with the reason when you point at it. Both are advice. Nothing is filed or trashed until you press a key, and the keys never move.

It learns from every decision that goes through the Mac — its keys, the phone page, and the iPhone app and watch in Remote — and from your whole filing history the first time 0.7.1 opens. ⌘Z takes back what a mistake taught it. On Windows 0.6.3 and in the iPhone app’s Cloud mode, a key glows the older way: a copy already lives there, or that genre usually goes there.

The auto page is the tab marked Auto, after your last page: your ten most-used folders, busiest first, with recent filings counting for more. It’s ranked from what you’ve filed each time Soundboy opens, and holds still while you work, so a key never changes under you. ↻ beside the tabs re-ranks it there and then. Reach it with ⇧ and its position: ⇧2 when you have one page.

The folder shelf

⌘B, or Folders in the transport row, swaps the queue for every folder in your library. Search it, and click a folder to file the playing track into it, or drag the track’s title onto one. Drag a folder onto a number key to put it on that key. Tell it where your library lives in Settings ▸ Folders ▸ Library folders: up to four top folders, and the shelf lists folders up to two levels inside them.

Double-presses

A stuttered double-press files one track, not two. Holding a key down doesn’t repeat it.

Before and after a crate

Before you start

When a new batch lands, a Before you start strip says how many tracks are already in your library and which came in more than one cut, so you know what’s worth your ears before the first track plays. Click the count already in your library to jump to the first of them. Dismiss hides the strip.

Dupe?

A track that matches one already in your folders shows Dupe? with the folder’s name. Matching ignores accents, leading track numbers, “&” versus “and”, punctuation and bracketed extras. It knows clean from dirty, extended from radio edit, and one remix from another, so keeping both of a pair doesn’t set it off. The question mark is honest: it’s a guess from the name, so it warns and never blocks.

Exact copies

Tracks that are byte-for-byte copies of files already in your library are offered as one sweep: Trash N byte-identical, in the Before you start strip. There’s nothing in them to audition. One ⌘Z brings them all back.

Skipped tracks

S leaves a track in the download folder and moves on. ⇧S takes you back through the ones you skipped, and Crate cleared counts them.

Crate cleared

The last track ends on Crate cleared: what was filed, trashed and skipped, how many went into each folder, and how long it took. Review skipped plays the skipped ones again, and Rescan picks up anything that has arrived since.

Pace

Beside the count of tracks left, the header shows about how long the rest will take and how many tracks an hour you’re sorting. Point at it for how many you’ve sorted and the typical time a track takes you. That’s a median, and a gap of more than two minutes counts as a break, so one long pause doesn’t skew it. The sidebar and the phone page show your pace too.

The log

Every filing is recorded, one line each, in a daily file on your disk (Help ▸ Open Session Logs). It notes where every file went and when.

Purge mode

For a folder you’ve already sorted that has grown too big. Nothing is filed anywhere: each track is kept where it is or purged to the Soundboy Trash.

• ⇧P, the Purge switch at the top of the window, or Crate ▸ Purge Mode for This Folder turns it on for the folder you’re in. It remembers the setting per folder.
• K keeps a track, ⌫ purges it, and ⌘Z undoes either.
• Kept tracks are remembered, so the next time you open the folder you only hear the ones you haven’t decided on.
• Start over forgets what was kept, so every track plays again. It asks first. Purged tracks stay purged.
• Done takes you back to the normal keys.

On the phone, swipe the track right to keep it and left to purge it. Let go before the line and it springs back. See iPhone and iPad app.

Continuous play

C, the ↻ beside play, or Crate ▸ Continuous Play turns it on. When a track plays to its end, the next one starts from the beginning. Nothing is decided for you: the finished track stays unfiled, and at the end of the queue the music stops. It’s for listening through a crate hands-free, then filing the ones that stand out.

Voice mode

Say where a track goes. It works on the Mac (V, the Mic switch at the top of the window, or Crate ▸ Voice Mode), and in the iPhone and iPad app in both modes. The first time, macOS or iOS asks for the microphone and speech recognition. Speech is recognised by Apple, on the device where it can be, and Soundboy keeps nothing.

What to say

How it tells you from the music

• Short and alone. Five words at most, one command, and the rest only small words like “it”, “that”, “put” or “please”. “Trash it” works. “I’m gonna trash this whole playlist” doesn’t.
• Over music it listens for a command with a pause on either side, so a lyric has to go quiet around the word before it can do anything.
• One track per command. A second command said right after the first is held back, so a stutter or a count-in can’t file tracks you haven’t heard. “Undo” always goes through.
• “Stop” isn’t a command: it’s in too many lyrics. Say “pause”.
• “Keep” only counts in Purge mode. Anywhere else it’s just a word.

On the Mac, the status bar shows what it heard and what happened, like “three” → filed to slot 3, and Settings ▸ Remotes ▸ Voice mode lists what it heard lately, with the reason each did or didn’t act. On the phone, the line under the switch shows the same. Tap it to see the last twenty-five things it heard, near misses included.

Microphone, on the phone

Tap the voice line and choose which microphone it uses:

• AirPods when the music stays full quality: in Remote mode always, since the music plays on the Mac. In Cloud mode only AirPods that record in high quality, otherwise the iPhone mic.
• AirPods, even in call quality: hears you from anywhere. In Cloud mode, AirPods without high-quality recording play the music in call quality while voice mode is on.
• iPhone mic: never the AirPods.

The menu bar, the Dock and media keys

New in 0.7.0, on the Mac: ways to sort with the Soundboy window hidden behind whatever else you’re doing. They follow the same rules as the keyboard, so none of them can do anything a key couldn’t.

The menu bar deck

Soundboy’s speaker sits in the menu bar with the number of tracks left beside it. Click it for the menu bar deck: the track, how far in you are, and Already filed? when you might own it. Then Undo, back 15 seconds, Play, Skip, Trash, and the pads on the page showing, each with its number. The pad Soundboy would suggest is ringed. In Purge mode, Purge and Keep take the pads’ place. Open Soundboy brings the window back.

The keys work there too: the numbers file, Space plays and pauses, ⌫ trashes, S skips, M sends to Maybe, K keeps, ← and → jump, ⌘Z undoes and Esc closes it.

Right-click the speaker, or Control-click it, for the Dock’s menu plus Open Soundboy, Settings…, Show in Menu Bar and Quit Soundboy. Untick Show in Menu Bar to take it out of the menu bar; tick it again in the Dock icon’s menu, or turn on Settings ▸ Window ▸ Show in the menu bar.

The Dock

Soundboy’s Dock icon shows the same count of tracks left. Right-click it for the track and how many are left, then Play, Trash, Skip, Maybe, Undo (it names where the track goes back from), File to with the pads on the page showing, and Keep on Top and Show in Menu Bar. In Purge mode it offers Purge and Keep instead of Trash, Skip, Maybe and the pads.

Now Playing and media keys

The track shows in Control Center’s Now Playing, with the Soundboy icon. The play key on your keyboard, AirPods and headphone buttons play and pause. Next skips the track: it never trashes or files anything, because those buttons are too easy to press by accident. Previous jumps back 15 seconds, or as far as your arrow keys jump. Drag the playhead in Control Center to move through the track.

Your DJ software

Settings ▸ Playlists ▸ Also file into DJ software playlists. Every track you file also goes into a playlist named after its key, which is the folder’s name unless you renamed the key, in each app you tick. The folders are still where your files really live, so this is a copy of your sorting. ⌘Z takes a track back out of all of them. It’s off when sorting a Dropbox, because the playlists point at files on this computer.

The export folder is Music/Soundboy Playlists unless you change it.

The folder in the file

Settings ▸ Folders ▸ Write the folder into each track’s tags puts the key’s name in each MP3’s Grouping tag, so rekordbox, Serato and Traktor can show it. Only MP3s are written. The audio and artwork are untouched, and undo puts the old tag back.

Phone page, Stream Deck, MIDI

Your phone or iPad, in the browser

1. Turn it on

   On the computer: Settings ▸ Remotes ▸ turn on Sort from your phone. The first time, macOS asks whether to allow incoming connections: allow it.

2. Scan the code

   Scan it with the phone’s camera and open the link. The phone must be on the same Wi-Fi.

3. That’s it

   The page has the waveform (tap to jump), transport, the ten keys with page switching, Maybe, Skip, Trash, Undo, Purge mode, Continuous, your pace, and every folder: search them, tap one to file into it, or hold one to put it on a key.

Away from home: put Tailscale on the computer and the phone, signed in to the same account. Open the same link with the computer’s Tailscale name in place of its address, keeping the port and code. The computer has to be awake.

Stream Deck

Use the Stream Deck’s own Hotkey action to send the F13–F21 keys in Every key, with Work without focusing the window on. They file into whichever page is showing. A Soundboy plugin, with keys that show the playing track and the folder behind each one, is coming.

MIDI

Settings ▸ Remotes ▸ Controller. Choose Learn beside a command, press the pad, done. The same pads work in every profile. A small pad controller such as an Akai LPD8 makes a good filing console. A MIDI controller shared with your DJ software sends its notes to both, so a dedicated pad is simpler.

Apple Watch without the app

With Sort from your phone on, Settings ▸ Remotes ▸ Apple Watch lists a web address for each action. In the Shortcuts app, make a shortcut with Get Contents of URL for each one, then put them on a complication or the Action button. The Watch app does more, but this needs no beta.

iPhone and iPad app

One app, two modes, chosen with the switch at the top.

Remote mode

Controls the computer: the same page as the phone page, inside the app. A strip on top shows whether it can reach the computer and what’s playing. If it says Can’t reach the Mac, check that Soundboy is open with Sort from your phone on, and that the phone is on the same Wi-Fi, then tap Try again.

Cloud mode

Sorts a Dropbox from the phone. The computer can be asleep, or you may not have one at all. Filing is done by Dropbox on its own servers, so nothing downloads to move it. Only the track you’re hearing is downloaded.

1. Connect Dropbox

   You sign in on Dropbox’s own page, never in the app.

2. Pick a crate

   The folder to sort. Crates you sort often stay on a shelf, one tap away. Swipe one off the shelf to remove it; the folder stays in Dropbox.

3. Set up the pads

   Up to six pages of ten. Mirror the Mac’s pages… copies the computer’s keys in one go. Or Add pads…: search, pinned and recent folders, or make a new one. Tick several and they all become pads. Arrange pads lets you drag, rename, or move a pad to another page. A pad’s name is what voice mode listens for.

4. Start

   The deck is described below.

On the deck

• Transport: Undo, back 15, play/pause, forward 15, Skip. Tap or drag the waveform to jump.
• Pads file into their folder, and the page switcher is above them. Maybe and Trash sit below. A ringed pad is a suggestion: in Remote, the Mac’s; in Cloud, where that genre usually goes, or where a copy already is.
• Left · kept at the top opens the list of the crate. Left only hides what’s done.
• Continuous and Purge mode switches sit under the transport. In Purge mode the pads become Keep and Purge, and you can swipe the track itself: right keeps, left purges. Start over… brings back what you kept.
• Already in that folder? A banner asks: Keep both, Replace it, Skip it or Later. A replaced copy goes to Dropbox’s own deleted files, and undo brings it back.
• Exact copies of tracks you’ve already filed get one offer: Trash N or Not now.

The gear opens Setup: crates, pads, Maybe folder, Include subfolders, Purge mode for the current crate, Disconnect Dropbox and Report a problem….

iPad

The same app. On a wide screen the deck and the pads sit side by side, in the same order as on the phone.

Apple Watch

• Deck page: what’s playing, how many are left, the waveform, play/pause, back and forward, Trash and Undo. In Purge mode, Keep and Purge.
• Digital Crown: the computer’s volume, in Remote mode.
• Folders: every folder in one list, Maybe included. They file into the same folder whatever page the computer is showing.
• Mic: tap it and say one command, such as “three” or “trash it”. The same rules as voice mode apply, and it only listens after a tap.
• Cloud mode: when the phone is in Cloud mode, the watch controls the phone.
• Complication: how many tracks are left to sort, on the watch face.

When the watch can’t reach the computer by itself, it goes through the phone.

Dropbox

Settings ▸ Storage ▸ Where the music lives: This Mac or Dropbox.

• This Mac sorts folders on the computer, including folders that happen to be inside a synced Dropbox folder.
• Dropbox talks to Dropbox directly, and the files never have to download. Watching for new tracks uses Dropbox’s own change feed, and filing is done by Dropbox on its servers, so a big WAV files as fast as an MP3. A track downloads only when you play it.

Connect Dropbox… opens Dropbox’s sign-in page in your browser, so Soundboy never sees your password. The sign-in is kept in the system keychain, and you can revoke it at dropbox.com under Connected apps.

The two setups are kept apart. Connecting Dropbox doesn’t change your folders on the computer, and switching back finds everything as you left it.

What’s different on Dropbox: folders are picked with Soundboy’s own picker. Trash is a Soundboy Trash folder at the top of your Dropbox. Playlists and the Grouping tag are off. The exact-copies sweep only runs on the phone and on local folders. The phone page, Watch and Stream Deck work the same.

Settings

⌘, opens them. Changes save as you make them.

Report a problem… is at the bottom, whichever tab is open. Settings are kept in ~/Library/Application Support/Soundboy/config.json (Help ▸ Reveal Config File shows you the file).

When something’s wrong

The phone can’t reach the computer

Check four things: the computer is awake, Soundboy is open, Settings ▸ Remotes ▸ Sort from your phone is on, and the phone is on the same Wi-Fi. If you made a new code, scan the new one. Some venue and hotel networks block devices from seeing each other. Use Tailscale there (see Phone page).

A new download didn’t show up

⌘R rescans the folder and restarts the watch on it, which fixes a folder that was deleted and recreated, or swapped by a sync app. Check Include sub-folders if the track is inside a folder.

“Can’t preview this format”

The file is damaged or uses an unusual codec. It stays in the queue and can still be filed.

I trashed the wrong track

⌘Z. Or open Soundboy Trash in your home folder (or the top of your Dropbox) and drag it back.

I filed into the wrong folder

⌘Z puts it back in the download folder. The status line names the key you pressed, so you can see whether it was 4 or 3.

A Stream Deck key does nothing

Check these in order:

1. The key is set up in the Elgato app as a Hotkey action, and you pressed the real key into its field, not typed “F13”.
2. System Settings ▸ Privacy & Security ▸ Accessibility allows Elgato Stream Deck. If it’s already on, switch it off and on, then reopen the Stream Deck app.
3. Work without focusing the window is on.
4. Another app, such as Karabiner, BetterTouchTool or Keyboard Maestro, hasn’t claimed the key. Soundboy can’t use a key another app holds, so free it there.

Soundboy’s MIDI learn never sees a Stream Deck, because a Stream Deck sends keystrokes, not MIDI.

Voice mode doesn’t hear me

Say the command on its own, with a pause either side. Check what it heard and why it didn’t act: in Settings ▸ Remotes ▸ Voice mode on the Mac, or by tapping the voice line on the phone. On the phone, choose your AirPods under Microphone. If it says a permission is off, the button beside it (Open System Settings on the Mac) goes straight there.

The sidebar is gone

It folds away when the window is too narrow for it. Make the window wider, or check Settings ▸ Window ▸ Sidebar.

The window looks different since the update

That’s Studio, the new look in 0.7.0. Settings ▸ Window ▸ Skin has Deck, the original.

Windows says it protected my PC

The Windows version isn’t code-signed yet. Choose More info, then Run anyway, once.

Licence, updates, reports

The free month and your licence

Everything is on for a month from the day you start it. After that it’s $69 once (plus any sales tax or VAT where you live), not a subscription, with free updates for the current major version. Your licence is a key you paste in Settings ▸ Licence. It’s checked on your own computer, so it works offline and a venue with no signal can’t lock you out. Checkout isn’t open yet. If your month has run out, email hello@soundboyselecta.com and we’ll get you filing again.

If the month runs out in the middle of a session, you keep working. It’s noticed at the next launch. If you do nothing, filing stops and the app is still yours to open: the queue stays where it was and tracks still play.

Updates

New versions download quietly and install when you quit. The status line says when one is waiting, and Settings ▸ Updates shows your version and what’s new.

Reporting a problem

Settings ▸ Report a problem… (at the bottom) saves a plain text report to your Desktop and shows it to you in Finder, then opens an email to us. Read the report, drag it into the email, say what happened, and send. On the phone it’s in Setup, and opens the share sheet. Nothing is sent without you, and no crash data or analytics are ever collected.

Anything else: hello@soundboyselecta.com.