Created by: Aren Akian
Last updated: Jul 30, 2024
-
Bearsalmon is a Pure Data (PD) external written in C, built on top of the PD “vanilla” library
-
Bearsalmon can act as a buffer shuffler/swapper between two pd Array objects (⇧⌘ + A on MacOS or ⇧Ctl + A on Windows/Linux)
-
Like a Bear slicing a Salmon with his claw, Bearsalmon lets the user chop, shuffle, and mangle up a sample, wavetable, or any other arbitrary array in PD.
Writing a PD external itself is quite a steep learning curve at first, but proves to be an incredibly powerful extension to PD’s already-vast capabilities.
- Designing the external, namely, the decision to interface via messages, and which prototypes to use was the biggest challenge.
- However, messages proved to be a very extendable interface. Bearsalmon was only originally intended to “cut” through Arrays of samples (by setting regions of the sample to zero).
- As time went on, I developed the “swap” and “shuffle” message protocols that allow the user to swap regions of samples between two array objects.
In the future I would like to add more message input protocols, and develop a VST/Max4Live version using Max/MSP
To use Bearsalmon, you need to install the correct compiled binary for your system, in your externals folder.
- Mac (any 64 bit architecture): .pd_Darwin
- Linux (any 64 bit architecture): .pd_linux
- Windows (any 64 bit architecture): .dll
-
Find the location your PD externals folder
- Open PD > Preferences > Path to see the default path to your externals folder
-
Copy the “bearsalmon” folder containing the compiled binaries and the bearsalmon-help.pd files into the externals folder
Typically, the default externals path is as follows:
| Scope | Path |
|---|---|
| Application-specific: | /$PdPath/Contents/Resources/extra (this is inside the Pd Application (like Pd-0.49-1 in ~/Applications); right click it and choose "Show Package Contents", then navigate to "Resources/extra") |
| User-specific: | ~/Library/Pd (/Users/user_name/Library/Pd) |
| Global: | /Library/Pd |
| Scope | Path |
|---|---|
| Application-specific: | %ProgramFiles(x86)%\Pd\extra (for 64-bit OS and 32-bit Pd) or %ProgramFiles%\Pd\extra; this is inside the Pd Application (usually in C:\Program Files). This folder needs to be set to writeable. |
| User-specific: | %AppData%\Pd (usually in C:\Users\user_name\AppData\Roaming\Pd). |
| Global: | %CommonProgramFiles%\Pd (usually in C:\Program Files\Common Files\Pd). |
| Scope | Path |
|---|---|
| Application-specific: | /usr/lib/pd/extra if installed via a package manager (apt-get) or /usr/local/lib/pd/extra if compiled by yourself. |
| User-specific: | ~/.local/lib/pd/extra (preferred since version Pd-0.47-1) or ~/pd-externals (deprecated but still usable). |
| Global: | /usr/local/lib/pd-externals. |
In most cases, the “User-Specific” path is reccomended.
- If unsure, you can add a search path to your custom install location.
Note: Bearsalmon requires two sample arrays as its input parameters, otherwise the object cannot be created
- Open a PD project
- Inside the patcher, create two sample arrays, “array0” and “array1”
- (⇧⌘ + A on MacOS or ⇧Ctl + A on Windows/Linux)
- Create an object (⇧⌘ + 1 or ⇧Ctl + 1)
- type in “bearsalmon array0 array1”
- Send messages to the bearsalmon object
- In order to manipulate the two arrays, you must send messages to the bearsalmon object via a message box or a Bang object, for example “cut 250”
- The message prototypes are detailed below
- Follow the steps above to create two sample arrays, and a bearsalmon object that contains them. Use a tabread~ to play either of the arrays (like in the help file)
- Load some samples into both arrays using tabwrite or read
- These can be wavetables, oscillator shapes, or audio samples of any length
- Then send messages to bearsalmon such as “cut 0 150 300” or “swap 128 256” or “shuffle 32”
- Make sure the bounds of your messages fit within the sample length of the two arrays
- Get creative and set off several messages at once using bangs, or sequences of messages using metronomes or other automation!
- Mangle those samples like the bear you are.
- For examples or further help, open “bearsalmon_help.pd” included in this repo.
Info: Sending a bang to the bearsalmon object will output some information regarding the arrays.
Arguments:
- BANG - output some information
Message box prototype: “cut array_sel startframe endframe”
Arguments:
- array_sel - The target array. Can be either 0 or 1, corresponding to the array0 and array1, respectively
- startframe – the first frame in the range of array elements to be cut
- endframe – the last frame in the range of array elements to be cut
Info: Cut modifies the target array over the range startframe, to endframe, setting the values over this range to zero.
- This method was implemented such that each call to “cut” also updates the GUI of the array in the patch window, providing useful (and fun) visual feedback to the user.
Message box prototype: “swap startframe endframe”
Arguments:
- startframe – the first frame in the range of elements to be swapped
- endframe – the last frame in the range of elements to be swapped
Info: This method is similar to cut, as it operates on a given range of elements. However, swap modifies both arrays in the bearsalmon object by swapping their elements over the specified range. The C-implementation of this uses the classic method of array swapping: Given arrayA and arrayB, and a range of indices:
- Store the desired range of elements from arrayB in a temporary local buffer
- Copy the desired range from arrayA to the correct indices of arrayB
- Copy the data from the temporary buffer to the correct indices of arrayA
Message box prototype: “shuffle segment_width”
Arguments:
- Segment_width – the desired width of the segments to be shuffled, in frames
Info: shuffle modifies both arrays so that they contain alternating segments of samples from both arrays, of length segment_width. Basically, this function performs a swap, on every other segment of elements.
If given a segment_width, n, the first array will contain n samples from the second, then n samples of its original array, then n samples from the second, and so on.
For Example:
- Array0 = {0,0,0,0, 0,0,0,0}
- Array1 = {1,1,1,1, 1,1,1,1}
Sending the bearsalmon object the message: “swap 2” makes it so that :
- Array0 = {1,1,0,0, 1,1,0,0}
- Array1 = {0,0,1,1, 0,0,1,1}
The C implementation of shuffle uses calls to a modified version of the swap function I wrote, except it does not update the GUI in between each swap. This “quickswap” function helps improve the speed of this shuffle operation.
If the external does not run in PD, or causes any issues, you may need to recompile the included source code for your system. I recommend using pd-lib-builder
- PD Docs: Externals
- pd-lib-builder
- Designing Audio Objects for Max/MSP and Pd by Eric Lyon