A free, open-source, keyboard-focused digital audio workstation (DAW). Written in C, using SDL (https://libsdl.org/).
- Disclaimer
- Compatibility
- Dependencies
- Installation
- Keyboard command shorthand
- Quickstart (getting comfortable)
- User manual
- Function reference
Jackdaw is a work in progress and has not been officially "released." What's available here is surprisingly powerful, fun to use, and can definitely be used to make music, but I do not guarantee that everything will work perfectly or as expected.
Jackdaw is compatibile with macOS and Linux.
Jackdaw currently depends on POSIX system APIs for threading and synchronization, directory navigation, timing, and inter-process communication.
Jackdaw depends on the SDL2 library, and related SDL2_ttf library.
Currently, the only way to install Jackdaw is to build it from the source code. The first step is to clone the repository:
$ git clone https://github.com/chvolow24/jackdaw.git
Two scripts are provided in this repository to make installation and updating easier: install.sh and update.sh.
Executing install.sh will attempt to install Jackdaw's dependencies (SDL2 and SDL2_ttf) on your system. In order to do so, it will also install homebrew on macos if not already installed. It will then build the jackdaw executable, and move it to /usr/local/bin, so that you can run it from the command line in any directory.
update.sh pulls any available updates from the remote repository, re-executes itself*, and then moves the executable to /usr/local/bin.
*This is so that you don't have to git pull in order to run the latest version of update.sh. But it would also be a great way for me to run malicious code on your computer! Proceed with caution (or trust).
Once install.sh completes execution, you can launch jackdaw on the command line:
$ jackdawIf you prefer not to run my bash scripts, you'll need to manually install the dependencies, build the project, and then do whatever you want with the executable.
Detailed instructions for installing SDL can be found on their wiki, but here's a summary:
Homebrew should work just fine:
$ brew install sdl2
$ brew install sdl2_ttfYou may want to build SDL from source by default (again, see wiki) instead of using apt-get; I found that the version of SDL provided by apt-get on ubuntu was too old.
SDL2_ttf can be installed with the package manager, though:
$ sudo apt-get install libsdl2-ttf-2.0-0
$ sudo apt-get install libsdl2-ttf-devNavigate to the main jackdaw directory (where you cloned this repository) and run make:
$ makeIf there are errors, please feel free to create an issue on this repository; I'd be happy to look into it.
If make executed successfully, there should be an executable named jackdaw in the current directory.
$ ./jackdawAlthough the mouse can be used for almost everything, Jackdaw is fundamentally a keyboard-driven application. Here are some examples of keyboard commands you'll see written in the application and in this documentation:
n......................................press the 'n' key
p......................................press the 'p' key
C-s...................................hold down 'command' OR 'ctrl', and press the 's' key
A-t....................................hold down 'alt' OR 'option' and press the 't' key
C-S-o.................................hold down 'command' OR 'ctrl', AND 'shift', and press the 'o' key
S-<ret>..............................hold down 'shift' and press the 'return' or 'enter' key
When a hyphen is present (as in C-s) it means you need to hold down one or more modifier key before striking the final key to invoke the command.
Capital C stands for the "Command" OR "Control" key. Jackdaw does not distinguish between these two keys.
Capital S stands for the "Shift" key.
Capital A stands for the "Alt" or "Option" key. (Again, no distinction is made)
Capital K indicates that you must hold down the 'K' key, which is used as a modifier in very specific circumstances.
So, C-S-o means hold down the control (or command) key and the shift key, and then press 'o'.
Most of the final keys are named by a letter or number, except for these:
<ret> means 'return' or 'enter'
<tab> means 'tab'
<spc> is the spacebar
<del> is the 'delete' or 'backspace' key (no distinction)
<up>, <down>, <left>, and <right> are the arrow keys
This will all be familiar to emacs users, and hopefully not too painful for everyone else.
This section is a brief tutorial meant to familiarize you with the most basic and frequently-used operations in jackdaw. From there, you can reference the user manual to learn about the other things you can do in the program.
The first thing you'll probably want to do upon opening jackdaw is to add a track or two. You can do this with
C-t
(Hold down cmd or ctrl and hit t).
The track input will be set to the default system audio input device, but you can change the current track input if you like with C-S-i (ctrl-shift-i or cmd-shift-i). A list of available input devices will appear. Use n (for 'next') to go to the next item in the list, and p (for 'previous') to go to the previous. (These keys will be used a lot). Hit <ret> to choose the currently-highlighted device.
Tip
n and p are used globally for "next" and "previous", or "down" and "up". The f and d keys are mapped to all the same commands, and can be used instead if you prefer them.
Once you have selected an appropriate audio input device, you can start recording audio into jackdaw with r. After making some noise at your computer or microphone, stop recording with r.
You should now see a clip on your timeline, with an audio waveform representing the audio you just recorded. You can rewind over the clip, pause, and play it back with the j (rewind) k (pause) and l (play) keys.
If you tap l or j multiple times, the playback speed will double.
These are jackdaw's most important key commands!
The clip you recorded landed on the first track by default. You can again use the n and p keys to move the track selector up and down. Try rewinding back to the beginning of the recording you made, selecting a different track, and recording some new audio.
Now that you've created some multi-track audio, you might want to export it to a wav file to show your friends.
First you'll need to place "in" and "out" marks on your timeline with i and o, which will place the mark at the current playhead position. You'll need to play/rewind/pause a bit (jkl! jkl!) to get the playhead positioned correctly to set the marks. Once you have placed in and out marks such that some portion of the timeline is visibly marked, you can export to a wav file with S-w.
You will be prompted to type a file name. Hit tab or <ret> to apply the current name, and move down to the directory navigation pane. Then, use n and p to navigate through the filesystem to the directory where you want to save the file. Subdirectories are displayed in green. The double dots ("..") will bring you up one directory. Finally, use <tab> to move down to the "Save" button, and then <ret> to save the file with the current name, in the currently open directory. (Or, use C-<ret> to "submit the form" and save the file.)
If you want to revisit this project later, you can save a project file (.jdaw) with C-s.
You will be prompted to enter a project name (which must include the .jdaw extension), and can then hit <ret> or <tab> to move down to the directory navigation pane. Navigate to the location at which you want to save the project (with n and p), and submit the form with <tab> and then <ret>to complete saving.
At any time, you can summon a menu with a list of available actions (and keyboard shortcuts) with C-m or C-h ("m" for menu, "h" for help). The menu will display a taxonomy of the available user actions. Navigate with n, p to move the selection up or down, and j and l to move left and right between columns. Then use <ret> to select. Use m (or h or <esc>) to dismiss the menu.
You can also summon the menu by clicking on the "hamburger" in the upper-right corner of the window.
Summoning these menus when in doubt is the best way to learn the available keyboard shortcuts.
Timeline navigation functions are all within easy reach of your right hand:
j : rewind (multiple taps to rewind fast)
k : pause
l : play (multiple taps to play fast)
In addition to the keyboard functions listed above, you can also adjust the playback speed dynamically (if already playing back) with the mousewheel or trackpad:
S-<scroll> : adjust speed (fine)
C-S-<scroll> : adjust speed (coarse)
h : move view left
; : move view right
, : zoom out
. : zoom in
C-<scroll> : zoom in or out
These zoom functions will center on the current playhead position. Using the mousewheel/trackpad to zoom will center the zoom on the current mouse position.
The track selector is how you indicate which track you are doing things to. The track console (left side) is highlighted in orange if the track is currently selected.
n : move selector down (next track)
p : move selector up (previous track)
The "cursor" (as in "[do thing] at cursor") is the location on the currently selected track under the current playhead position. So, "grab clip at cursor" means "grab the top clip on the currently selected track that intersects with the current playhead position."
Keystrokes that move the track selector or move the playhead can therefore also be thought of as ways to move the cursor:
n or f : cursor down
p or d : cursor up
j : cursor left
l : cursor right
The cursor concept is one of jackdaw's unique strengths.
"In" and "out" marks can be set to mark a range on the current timeline. They also be used as handy jump-to points.
You can also jump to the start of the timeline (t=00:00:00000) with S-u, which is helpful if you get lost.
i : mark in
o : mark out
S-i : jump to in mark
S-o : jump to out mark
S-u : jump to t=0
S-j : jump to start of clip at point
S-l : jump to end of clip at point
When you move the track selector with n and p, the timeline will automatically refocus such that the selected track is visible. You can also scroll through tracks with a mouse or trackpad. Scrolling horizontally translates the timeline in the manner of h and ;.
Holding Cmd or Ctrl and scrolling on the timeline will zoom in or out.
r : start or stop recording
When you hit r, audio recording will begin on all activated tracks, or, if no tracks are activated, on the currently selected track. Clips are created on each of these tracks beginning at the current playhead position. When you stop recording, these clips will be populated with the audio data you just recorded.
You can record from multiple audio devices at once, simply by setting different inputs on different tracks, activating each of those tracks, and hitting r.
In the current version of jackdaw (v0.4.0) all tracks are stereo audio tracks.
C-t : add a track
C-<del> : delete the currently selected track
Activating tracks (as opposed to merely selecting them) is a way to do things that might normally be done to only one track to multiple tracks at once. Here are things you can do to multiple tracks at once:
- adjust volume
- adjust pan
- record audio
- grab clips
<ret> : Activate or deactivate the currently-selected track
` : Activate or deactivate all tracks
Muted tracks will not be read during playback, or when exporting a .wav file.
If any track on the timeline is soloed, only tracks that have been soloed will be read. The S button will be red on any un-soloed tracks to indicate that they are effectively muted.
m : Mute currently selected track (or active tracks)
s : Solo currently selected track (or active tracks)
Track volume can be attenuated or boosted. Stereo tracks can be panned to the left or right. The pan implementation is fairly primitive; panning to either side will simply attenuate the opposite channel by an amount proportional to the pan amount.
Tip
These key combinations can be held down for continuous adjustment.
S-- : Volume down (selected or active tracks)
S-= : Volume up (selected or active tracks)
S-9 : Pan left (selected or active tracks)
S-0 : Pan right (selected or active tracks)
(Note that the pan adjustment keystrokes are the left and right parens.)
The track input can be set to any of the available system audio devices (e.g. built-in laptop microphone, external microphone) or one of two special inputs, which are described below.
C-S-i : Set track input
If you hold down shift while moving the track selector up or down, the selected track will move with you.
S-n : Move selected track down
S-p : Move selected track up
You can rename the selected track with C-r, or cmd/ctrl + click the track name label box.
C-r : Rename selected track
Renaming a track or other object will put the program into "text edit mode", in which most keystrokes are read as text input rather than as keycommands. Use <ret> to complete your edit and "escape" text edit mode.
There are some very limited additional text editing commands that can be used while a text field is being edited:
<ret>, <tab>, <esc> : Escape text edit mode (complete edit)
<del> : Backspace
<right>, C-f : Move cursor to the right
<left>, C-d, C-b : Move cursor to the left
C-a : Highlight all text
C-<del> : Delete the currently-selected track
A clip is a chunk of audio data represented on the timeline.
In general, this document and the application itself refer to the rectangles on the timeline that contain audio data as "clips."
The audio data itself does live in a object called a Clip, but the information mapping that audio data to a position on the timeline is an object called a "clip reference", type ClipRef.
A clip can have many clip reference. The audio data associated with the clip is not duplicated; therefore, when copying clips or portions of clips using Source Mode, you are not actually copying any audio data; you are merely creating additional references to the clip.
The blue or green color of any given clip reference on the timeline is not particularly meaningful in this version of jackdaw (0.4) and can be safely ignored.
Clips that have been "grabbed" can be deleted or moved around on the timeline.
g : Grab clips at cursor(s)
Using this function will grab any clips that intersect the playhead position on the currently selected track OR all active tracks. If all interesecting clips are already grabbed, the function will un-grab all clips.
A clip can also be "grabbed" with C-<click>.
C-k : Toggle drag clips
If clip dragging is enabled, an indication will appear in the status bar at the bottom of the screen indicating how many clips are currently grabbed.
Moving the track selector will pull all currently-dragging clips along with it.
S-c : Cut clips at cursor
This will cut any clips on the currently selected track at the current playhead position in two, so that you can independently move or otherwise modify each part.
C-S-r : Rename clip at cursor
See "Editing text" for more on text edit mode.
Jackdaw provides an interface for extracting samples from an audio clip, and dropping references to those samples in your timeline.
C-1 : Load clip at cursor to source
If there is a clip at cursor, this function will load that clip to the source area near the top of the window.
S-1 : Activate or deactivate source mode
In source, you can play back, scrub through, and set marks in the clip that has been loaded into the source area. The marks you set here will determine which portion of the clip is dropped into your timeline when you:
b : Drop clip from source
This creates a new clip reference on your timeline, at the current playhead position, on the currently-selected track.
Every time you drop a clip into a timeline from the source area, jackdaw will save information about that drop. If you then drop something else into your timeline (either a different clip or the same clip with different marks) with b, you will be able to once again drop the previously-dropped clip with v. Another new drop will move the clip stored at v to c, so that you have unique clips that you can drop into your timeline with any of those three keys. Etc. for subsequent drops and x and z.
b : Drop clip from source
v : Drop previous clip (-1) from source
c : Drop previous clip (-2) from source
x : Drop previous clip (-3) from source
z : Drop previous clip (-4) from source
Jackdaw provides a way to use multiple workspaces in a single project. Each of these is a "timeline," which is just a collection of tracks with associated clips.
A-t : Create new timeline
A-l : Go to next timeline
A-j : Go to previous timeline
A- : Delete current timeline
When creating a new timeline, you will be prompted to enter a name. Type the name, hit <tab> or <ret> to move to the "Create" button, and then <ret> again to complete naming the timeline.
Jackdaw is capable of opening two types of files: .wav and .jdaw (project) files. This can be done at launch time on the command line:
$ jackdaw PATH_TO_FILEIt can also be done during runtime.
C-o : Open a file
If a .wav file is opened, it will be loaded as a clip to the currently-selected track, starting at the current playhead position. If a .jdaw file is opened, the current project will be closed and replaced with the project saved in the .jdaw file.
A .jdaw file stores a jackdaw project, including all of its timelines, tracks, clips, effects, automations, etc.
C-s : Save project as
You will be prompted first to edit the current project file name. The file extension must be .jdaw or .JDAW; the program will encourage you to fix this if you make a mistake. Hit <tab> or <ret> to finish editing the name. Now, the directory navigation pane will be active, and you can use n, p, and <ret> to navigate through the filesystem to the directory where you would like to save the file. When satisfied, type <tab> and then <ret> (or just C-<ret> to save.)
Like everything else about jackdaw, the .jdaw file format is open and is described in the jdaw_filespec directory. (The current version as of writing is described in jdaw_filespec/00.13).
Only two track effects are available now, but more will be available soon. A track effect is applied only to clips on the "effected" track. In other words, these are "insert" effects; "sends" will be added in a later version of jackdaw.
S-t : Open track effects
You might choose to navigate the tab view with your mouse, but it can be done with the keyboard as well. A single element on a page (e.g. slider, toggle, button) is selected, and the selection can be changes with <tab>. Actions can be performed on the currently-selected
<tab> : Cycle through page elements
S-<tab> : Cycle through page elements in reverse
h : Nudge slider left
; : Nudge slider right
<ret> : Select / toggle / cycle current element
You can also navigate to other tabs:
S-h : Tab left
S-; : Tab right
The FIR ("finite impulse response") filter effect is an FFT-based "windowed-sinc" filter. It can be configured to have a low-pass, high-pass, band-pass, or band-cut frequency response. The cutoff frequency and bandwidth are adjustable parameters, as is the length of the impulse response. This last parameter affects the "steepness" of the frequency response curve.
Note
This is a computationally expensive effect. Applying FIR filters to many tracks may begin to cause audio playback issues if there is audio on those tracks that needs to be processed. (My 2020 macbook air maxes out at around 45.)
The frequency response of the filter is shown. When the filter is active, and playback is occurring, the frequency domain of the filtered audio track is also shown.
The delay line is a simpler effect and has three parameters: time, amplitude, and "stereo offset." As in any delay line, the delay time is the amount of time between echoes, and the amplitude is the relative amplitude of each successive echo. "Stereo offset" delays playback of the delay line buffer in the left channel by some proportion of the delay line length, expressed as a value between 0.0 and 1.0. In other words, with a nonzero stereo offset, you will hear echoes at different times in your left and right ears.
Dynamic changes to the delay line length during playback are accomplished by "squeezing" or "stretching" the existing delay line buffer into the space of the new-length buffer. The squeezing and stretching produce pitch-shifting effects which are better experienced than described.
Automation is available for the following track* parameters:
- Volume
- Pan
- FIR Filter cutoff frequency
- FIR Filter bandwidth
- Delay line length
- Delay line amplitude
- Play speed
*Play speed is a global parameter, not a track parameter. If play speed automation is added to multiple tracks, only the last of them will be read.
C-a : Add automation to track
a : Show / hide track automations
(Note that n and p (or f and d) can be used to cycle through the radio button options, and <tab> and S-<tab> can be used to move between the selector and the "add" button. The mouse is available but optional.)
Use C-<click> to add a keyframe to an automation track. You can then drag the keyframe to the desired position. If you release cmd/ctrl and hold shift, the keyframe will will snap to the same vertical position as the previous keyframe, creating a flat segment. If you hold cmd or ctrl AND shift, the keyframe will snap to the position immediately after the previous keyframe, creating a near-vertical segment.
While an automation is in "write" mode, any changes to the automated parameter will be recorded on the automation track during playback. Any existing keyframes intersecting with the newly-written portion will be overwritten.
The easest way to accomplish this is to "record" on the automation track exactly as you would on an audio track: navigate the cursor to the automation track with n and p (or f and d) and hit r to start recording. Hit r again to stop.
r : Start / stop recording automation (when automation track selected)
When an automation track is selected, you can delete a range of keyframes by marking (with i and o) a section of the timeline and hitting del.
del : Delete keyframes in->out (when automation track selected)
Jackdaw retains a 100-event long history of user events. Generally, any changes to the project state -- those that would affect the saved .jdaw file -- can be undone. Actions that only affect the superficial state of the program cannot.
Caution
In the current jackdaw version (v0.4.0), track volume and pan adjustments, as well as adjustments to track effect parameters (e.g. FIR filter cutoff frequency) cannot be undone. This is a technical limitation and will be fixed in a future version of jackdaw.
Objects that you delete will not be permanently deleted until the program is closed or the deletion event drops off the end of the event history.
Jackdaw undo is linear. That means that if you undo some number of changes, and then make a new change, you will lose the ability to redo those previously-undone events.
C-z : undo
C-y / C-S-z : redo
Jackdaw will have access to all of the audio devices (speakers, microphones, etc.) that your system knows about. In addition, there are two special audio inputs that you can use to record audio onto a track.
Jackdaw is capable of using its own audio output as an audio input. This makes it very easy to create mixdowns on-the-go, or to record some of the fun sounds you can make by scrubbing through your timeline and dynamically adjusting the playback speed.
Note
This is an experimental feature and is not yet reliable.
Pure data (often "Pd") is a graphical audio programming environment developed by Miller Puckette. It is very similar to Max, which was also developed by Puckette, but unlike Max, is free to download and use. Pure data can be used to create things like synthesizers and drum machines, as well as sound production programs that are too unusual to be designated as such.
Pd also provides a method for writing your own objects (called "externals") for use in the program. Jackdaw is capable of communicating with (and receiving audio from) Pd by means of an external called pd_jackdaw~. This external needs to be built and loaded into Pd.
I have provided the source code for pd_jackdaw~ here (pd_jackdaw/pd_jackdaw.c), but have not yet provided the means to build it or load it into Pd. If you are so inclined, you may figure out how to do this using pd-lib-builder.
The pd_jackdaw~ objects inlets are for the left and right channels of audio. If jackdaw is open and a pd_jackdaw~ object is created, the two programs will do a handshake (exchange a series of signals) before setting up a block of shared memory, which they use to exchange audio data. If DSP is enabled in Pd and a track input is set to "Pure data" in jackdaw, you should be able to record audio directly from Pd just as you would from a microphone.
- Summon menu : C-m, C-h
- Quit : C-q
- Undo : C-z
- Redo : C-y, C-S-z
- Show output spectrum : S-f
- Save Project : C-s
- Open File (.wav or .jdaw) : C-o
- Next item : n, f
- Previous item : p, d
- Next section : C-n, C-f, C-<up>
- Previous section : C-p, C-d, C-<down>
- Choose item : <ret>, <spc>, k
- Column right : l
- Column left : j
- Move menu up : <up>
- Move menu down : <down>
- Move menu right : <right>
- Move menu left : <left>
- go back (dismiss) : <del>, m, h, <esc>
- Play : l, e
- Pause : k, w, S-k
- Rewind : j, q
- Play slow : K-l, C-l
- Rewind slow : K-j, C-j
- Nudge play position left (500 samples) : <left>
- Nudge play position right (500 samples) : <right>
- Nudge play position left (100 samples) : S-<left>
- Nudge play position right (100 samples) : S-<right>
- Move one sample left : C-S-<left>
- Move one sample right : C-S-<right>
- Record (start or stop) : r
- Move track selector up : p, d
- Move track selector down : n, f
- Toggle automation read : S-r
- Move selected track down : S-n, S-f
- Move selected track up : S-p, S-d
- Move view right : ;
- Move view left : h
- Zoom out : ,
- Zoom in : .
- Set In : i
- Set Out : o
- Go to In : S-i
- Go to Out : S-o
- Go to t=0 : S-u
- Go to clip start : S-j
- Go to clip end : S-l
- Set default audio output : C-S-o
- Add Track : C-t
- Activate/deactivate selected track : <spc>, <ret>
- Activate/deactivate all tracks : `
- Delete selected track or automation : C-<del>
- Select track 1 : 1
- Activate track 2 : 2
- Activate track 3 : 3
- Activate track 4 : 4
- Activate track 5 : 5
- Activate track 6 : 6
- Activate track 7 : 7
- Activate track 8 : 8
- Activate track 9 : 9
- Open track settings : S-t
- Mute or unmute selected track(s) : m
- Solo or unsolo selected track(s) : s
- Track volume up : S-=
- Track volume down : S--
- Track pan left : S-9
- Track pan right : S-0
- Rename selected track : C-r
- Set track input : C-S-i
- Show or hide all track automations : a
- Add automation to track : C-a
- Grab clip at cursor : g
- Start or stop dragging clips : C-k
- Cut clip at cursor : S-c
- Rename clip at cursor : C-S-r
- Delete : <del>
- Load clip at cursor to source : C-1
- Activate Source Mode : S-1
- Drop clip from source : b
- Drop previously dropped clip (1) : v
- Drop previously dropped clip (2) : c
- Drop previously dropped clip (3) : x
- Drop previously dropped clip (4) : z
- Add new timeline : A-t
- Previous timeline : A-j
- Next timeline : A-l
- Delete timeline : A-<del>
- Write mixdown to .wav file : C-e, S-w
- Play (source) : l
- Pause (source) : k, S-k
- Rewind (source) : j
- Play slow (source) : S-l, K-l
- Rewind slow (source : S-j, K-j
- Set In Mark (source) : i, S-i
- Set Out Mark (source) : o, S-o
- Go to next item : n, f
- Go to previous item : p, d
- Go to next item (escape DirNav) : <tab>, S-n, S-f
- Go to previous item (escape DirNav) : S-<tab>, S-p, S-d
- Select item : <ret>, <spc>
- Dismiss modal window : m, h, <esc>
- Submit form : C-<ret>
- Escape text edit : <ret>, <tab>, <esc>
- Backspace : <del>
- Move cursor right : <right>, C-f
- Move cursor left : <left>, C-d, C-b
- Select all : C-a
- Next element : <tab>
- Previous element : S-<tab>
- Select : <ret>
- Move left : h
- Move right : ;
- Next tab : S-;
- Previous tab : S-h
...
[ LAST UPDATED 2024-11-13 WEDNESDAY ]
...