version 2.0 🔥

.gitignore

@@ -2,3 +2,6 @@
 CS-16.pdx/*
 CS-16.pdx
 TODO.md
+stub.lua
+CHANGELOG.md
+CS-16.pdx.zip

DEV.md

@@ -0,0 +1,64 @@
+# develop
+
+## building
+
+Building CS-16 is exactly like how you'd build any other Playdate game (in this case, the command is `pdc src/ CS-16.pdx`).
+
+However, I personally use [`just`](https://github.com/casey/just) to make things a little faster! If you install `just` or already have it installed, the default `just` recipe will build CS-16 and open it in the Playdate Simulator, presuming `PlaydateSimulator` is in `$PATH`.
+
+> note: the `just` recipes are only compatible with Linux or MacOS. the `justfile` may need to be modified if you are on Windows.
+
+> also, if you end up taking a look at the code, sorry in advance if it's a mess XD
+ 
+## visualizers
+
+### format
+A CS-16 visualizer at its core is just a function that gets called every playdate.update() loop, so you can do pretty much whatever you want with it!
+
+In order for it to be recognized by CS-16, your visualizer code must be either a standalone `.lua` file, or be in a folder by the same name as one of the `.lua` files.
+
+CS-16 requires that a visualizer returns a table with the name of the visualizer, as well as the function that will be called every update. When it is called, CS-16 will pass in a key-value table containing many values which you may find useful when creating a visualizer.
+
+Here's the code for one of my visualizers, called "bumper", as an example:
+
+```lua
+local function bumperUpdate(data)
+  if data.beat then
+    pd.display.setOffset(0, 3)
+  elseif math.floor(data.step) % 8 == 2 then
+    pd.display.setOffset(0, 1)
+  else
+    pd.display.setOffset(0, 0)
+  end
+end
+
+return {"bumper", bumperUpdate}
+```
+
+### building and importing
+Currently, there is no way to directly load Lua code from the Playdate's Data/ directory (most likely for security reasons), so you'll have to rebuild CS-16 with your custom visualizers in the source code.
+
+To do this, clone this repository with `git clone https://github.com/nanobot567/CS-16`. Then, navigate to the `src/` directory, and create a new folder named `visualizers` if it doesn't already exist. Here, simply paste your .lua files (or the folder containing your .lua file) and rebuild CS-16 with `pdc src/ CS-16.pdx` (or if you have [`just`](https://github.com/casey/just) installed, `just`).
+
+### visualizer key-value table data
+
+| key                  | type               | note                                                                                                                        |
+| -------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| tempo                | number             | pattern tempo                                                                                                               |
+| step                 | number             | pattern step                                                                                                                |
+| rawStep              | number             | pattern step, not rounded                                                                                                   |
+| length               | number             | pattern length                                                                                                              |
+| playing              | boolean            | true if pattern is currently playing                                                                                        |
+| beat                 | boolean            | true if current step is a beat                                                                                              |
+| tracks               | object table       | table of `playdate.sound.track`s in the pattern                                                                             |
+| trackNames           | string table       | table of the names of the tracks                                                                                            |
+| userTrackNames       | string table       | table of user-defined track names. if a name has not been set, the value at that track's index will be an empty string ("") |
+| trackSwings          | number table       | table of swing values for each track                                                                                        |
+| mutedTracks          | boolean table      | mutedTracks[trackNumber] returns true if the track is currently muted                                                       |
+| instruments          | object table       | table of `playdate.sound.instrument`s                                                                                       |
+| instrumentADSRs      | number table table | nested tables contain the attack, decay, sustain and release values in that order for each track                            |
+| instrumentLegatos    | boolean table      | legato status for each track                                                                                                |
+| instrumentParams     | number table table | tables within contain parameter 1 and 2 values for square wave tracks and TE synth tracks (phase, digital, vosim)           |
+| instrumentTransposes | number table       | contains the transposition value of each track                                                                              |
+| settings             | key-value table    | contains the user's settings. refer to your own `settings.json` file if you don't know what the key to a setting may be!    |
+| sequencer            | object             | CS-16's `playdate.sound.sequencer`*                                                                                         |

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Nanobot567
+Copyright (c) 2024 Nanobot567
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MANUAL.md

@@ -1,9 +1,10 @@
 # CS-16 manual
 
-In CS-16, there are three main screens, each of which will be explored in this manual:
+In CS-16, there are four main screens, each of which will be explored in this manual:
 1. `pattern`
 2. `track`
-3. `song`
+3. `fx`
+4. `song`
 
 You can swap between these screens by pressing `B` until the text shown says `screen`, and then cranking. This "crank mode" menu will be accessed often as you use CS-16.
 
@@ -33,7 +34,7 @@ To make placing down and editing notes at intervals easier, there is an option i
 
 ![](assets/autonote.gif)
 
-To edit the pitch of the note, cycle through the crank mode menu until you reach `pitch`, then crank like you did for `note status`. Changing the track, velocity, and note length are done this same way.
+To edit the pitch of the note, cycle through the crank mode menu until you reach `pitch`, then crank like you did for `note status`. Changing the track, velocity, note length, and swing are done this same way.
 
 You can start or stop the sequence by pressing A.
 
@@ -43,6 +44,8 @@ If you would like to input notes in real time, there is a `record` function in C
 
 While in record mode, the `A`, `B`, `up`, `down`, `left`, and `right` buttons are mapped to tracks in the song. When pressed, a note is placed at that step in the corresponding track. If quantization is enabled (not 1), then each note you place will be quantized to the nearest multiple of the quantization value.
 
+> swing is applied when you press `stop record`.
+
 ![](assets/liverecord.gif)
 
 ### track
@@ -58,6 +61,16 @@ In the system menu, there are two options, `copy` and `cpy mode`. To copy a trac
 
 ![](assets/copypaste.gif)
 
+#### renaming tracks
+
+To rename one of your tracks, hover over the track you would like to rename, enter the system menu and select `rename`.
+
+To remove your custom track name, enter the `rename` keyboard, delete all of the characters, and press `OK`.
+
+> note: there is a 10-character limit.
+
+![](assets/rename.gif)
+
 #### instrument editor
 
 To edit an instrument, select the track you want in the list. It will be marked with the number and the instrument type. Instrument types can be any of the following:
@@ -99,21 +112,76 @@ Within the file picker, you can enter folders or select a file using `A`, and ex
 
 If you have already selected a sample, however, there will be an extra option in the list: `edit sample`. In the `edit sample` screen, you can trim your samples. Pressing `left` or `right` changes the selected side, and pressing `up` or `down` changes the interval at which you trim the sample using the crank.
 
-If you are editing a sample that was recorded with the Playdate's microphone, you will see a waveform above the start and end frame locations.
+If you are editing a sample that was recorded with the Playdate's microphone and you have enabled `settings / sampling / save waveforms`, you will see a waveform above the start and end frame locations.
 
 ![](assets/sampleedit.png)
 
 > note: double and triple check your sample before you save it! when you trim it you cannot revert to the original sound.
 
+### fx
+
+![](assets/fx.png)
+
+In the `fx` screen, you can apply punch-in effects to your pattern. Currently there are four effects (ordered clockwise, starting from the top):
+
+1. `TAPE`: high-pass and low-pass filters
+2. `BTC`: bitcrush
+3. `WTR`: low-pass filter
+4. `OVD`: overdrive
+
+While in this screen, press A to activate or deactivate punch-in. The word `ACTV!` will appear at the center of the screen when it's activated. Once activated, the d-pad buttons enable the corresponding effect when pressed, and disable when not.
+
+It is possible to "lock" your button presses! Enable the effects you would like to lock, then switch the crank mode to `lock effect`. Crank clockwise until you see a "lock" icon appear in the bottom left of your screen. To unlock effects, either crank counter-clockwise to unlock all of them, or press the corresponding d-pad button when punch-in is active.
+
+If you would like to change an effect intensity (signified by the decimal number next to the effect), first ensure that punch-in is deactivated. Then, change the crank mode to `effect intensity` and press the d-pad button according to the effect you would like to modify. You'll know you're good to go when there's a box around the effect text. Now just crank until you reach your desired value! Intensities range from 0 (off) to 1 (full effect).
+
+> note: this can be done while an effect is applied, allowing for some pretty fun live performance stuff!
+
 ### song
 
-![](assets/song.png)
+![](assets/songscreen.gif)
 
 In the `song` screen, you can view and modify your song's global options, such as the tempo and pattern length (these can be modified via the crank). Your song name and author name is displayed at the top.
 
 > IMPORTANT NOTE! currently, the tempo can only be changed by intervals of 7.5 because of a bug in Playdate OS. as soon as a fix is implemented, this message will be deleted. 
 
-Here you can also save and load your songs via the Playdate OS menu. In the menu, you can access and change CS-16 settings, such as dark mode, crank sensitivity, and the name used to sign your saved songs.
+Here you can also save and load your songs via the Playdate OS menu. If you select `load`, you can also perform file operations on your songs, such as renaming, deleting, and cloning. You can press `right` to view file metadata as well.
+
+![](assets/fileops.gif)
+
+In the system menu, you can also access and change CS-16 settings, such as dark mode, crank sensitivity, and the name used to sign your saved songs. A full list of settings is below.
+
+- `general/`
+	- `author` (text value, default anonymous)
+	- `output` (audio output. can be auto, speaker, headset, or speaker and headset)
+	- `crank speed`
+	- `credits`
+- `behavior/`
+	- `play on load` (play pattern immediately on song load)
+	- `stop if sampling` (stop the pattern if you are currently sampling audio)
+	- `tempo edit stop` (stop the pattern when tempo is modified)
+	- `save .wav samples` (alongside .pda audio, save .wav files when sampling)
+	- `crank docked screen` (which screen appears when the crank is docked. `none` disables changing the screen)
+- `recording/` (as in tapping in a pattern)
+	- (button) `button track` (when record is active, this button will correspond to this track)
+	- `quantization` (quantize recording, can be either off [1], every 16th note [2], or every 8th note [4])
+- `sampling/`
+	- `sample format` (16 bit or 8 bit)
+	- `save waveforms` (save waveform images along with audio)
+- `ui/`
+	- `dark mode`
+	- `visualizer` (song screen visualizer options)
+		- `sine wave` (sine wave where tempo is proportional to frequency and pattern length is proportional to amplitude)
+		- `notes` (displays track active statuses)
+		- `stars` (purely decorational, but looks pretty awesome lol)
+		- `--- external ---` (below this are custom visualizers)
+	- `show number / total` (display current crank mode number out of total)
+	- `show note names` (display note names in pattern [C#4, F3, etc.])
+	- `animate scrn move` (animate screen transitions)
+	- `use system font` (use an alternate font)
+	- `show log screens` (display log screens, causes some moderate slowdown at the cost of coolness)
+	- `fx screen vfx` (when an effect is active, apply the corresponding screen visual effect as well)
+	- `50fps` (50fps refresh rate)
 
 ## other information
 
@@ -141,13 +209,22 @@ To manage your songs:
 2. navigate to `Data/user.*****.com.nano.cs16/songs/`
 3. add, copy, delete, or rename your songs, then eject your playdate when you are done.
 
+> if you are sharing your songs on the internet, you can set your author name in `settings / general`!!
+
 ### ways to improve performance
 
 All of these are things you can do to improve CS-16's performance and reduce frame drops.
 
-- In `settings/ui/`...
-    - Disable `visualizer`.
+- In `settings / ui /`...
+    - Disable all `visualizer` elements.
     - Disable `show note names`.
     - Disable `animate scrn move`.
+    - Disable `fx screen vfx`.
     - Enable `50fps`.
 - Use lower quality samples (ex. lower bitrate)
+
+### custom visualizers
+
+I have a few custom visualizers in this repository under `visualizers` (and maybe you'll find another one on the internet somewhere??? idk haha). To import these into CS-16, check out the visualizer `building / importing` section in the [DEV document](DEV.md).
+
+> note: by default, imported visualizers are disabled. head to `settings / ui / visualizers` to enable them.

README.md

@@ -1,11 +1,11 @@
 # cs-16 (cranky synth 16)
 a synthesizer for playdate
 
-<img src ="https://img.shields.io/tokei/lines/github/nanobot567/cs-16"><img src="https://img.shields.io/github/downloads/nanobot567/cs-16/total"><img src="https://img.shields.io/github/v/release/nanobot567/cs-16">
+<img src="https://img.shields.io/github/downloads/nanobot567/cs-16/total"><img src="https://img.shields.io/github/v/release/nanobot567/cs-16">
 
 <div style="align: center;"><a href="https://github.com/nanobot567/cs-16/releases/latest"><img src="https://github.com/Nanobot567/tAoHtH/blob/main/readme-graphics/Playdate-badge-download.png"></a></img></div>
 
-## [manual](https://github.com/nanobot567/cs-16/blob/main/MANUAL.md) | [license](https://github.com/nanobot567/cs-16/blob/main/LICENSE)
+## [manual](https://github.com/nanobot567/cs-16/blob/main/MANUAL.md) | [develop](https://github.com/nanobot567/cs-16/blob/main/DEV.md) | [license](https://github.com/nanobot567/cs-16/blob/main/LICENSE)
 
 ## features
 - 16 tracks
@@ -29,7 +29,11 @@ a synthesizer for playdate
 
 *track edit view*
 
-![song view](assets/song.png "song view")
+![fx view](assets/fx.png "fx view")
+
+*fx view*
+
+![song view](assets/songscreen.gif "song view")
 
 *song view*
 

example-songs/kinomu-alt/song.json

@@ -0,0 +1 @@
+[[["smp","smp","smp","smp","tri","squ","smp","smp","sin","squ","saw","tri","nse","poP","poD","poV"],[[{"velocity":1,"length":8,"note":60,"step":8},{"velocity":1,"length":8,"note":60,"step":104},{"velocity":1,"length":8,"note":60,"step":264},{"velocity":1,"length":8,"note":60,"step":360},{"velocity":1,"length":8,"note":60,"step":488},{"velocity":1,"length":8,"note":60,"step":504}],[{"velocity":1,"length":8,"note":60,"step":72},{"velocity":1,"length":8,"note":60,"step":168},{"velocity":1,"length":8,"note":60,"step":328},{"velocity":1,"length":8,"note":60,"step":424}],[{"velocity":1,"length":8,"note":60,"step":40},{"velocity":1,"length":8,"note":60,"step":104},{"velocity":1,"length":8,"note":60,"step":168},{"velocity":1,"length":8,"note":60,"step":296},{"velocity":1,"length":8,"note":60,"step":360},{"velocity":1,"length":8,"note":60,"step":424},{"velocity":1,"length":8,"note":60,"step":440},{"velocity":1,"length":8,"note":60,"step":456}],[{"velocity":1,"length":8,"note":67,"step":40},{"velocity":1,"length":8,"note":62,"step":104},{"velocity":1,"length":8,"note":62,"step":168},{"velocity":1,"length":8,"note":55,"step":232},{"velocity":1,"length":8,"note":67,"step":360},{"velocity":1,"length":8,"note":62,"step":456},{"velocity":1,"length":8,"note":67,"step":488}],[{"velocity":1,"length":256,"note":36,"step":8},{"velocity":1,"length":256,"note":31,"step":264},{"velocity":1,"length":128,"note":43,"step":360},{"velocity":1,"length":8,"note":48,"step":488}],[{"velocity":1,"length":8,"note":60,"step":200},{"velocity":1,"length":8,"note":55,"step":232},{"velocity":1,"length":8,"note":60,"step":264},{"velocity":1,"length":8,"note":67,"step":328},{"velocity":1,"length":8,"note":55,"step":360},{"velocity":1,"length":8,"note":63,"step":392},{"velocity":1,"length":8,"note":62,"step":456}],[{"velocity":1,"length":8,"note":60,"step":8},{"velocity":1,"length":8,"note":60,"step":56},{"velocity":1,"length":8,"note":60,"step":104},{"velocity":1,"length":8,"note":60,"step":136},{"velocity":1,"length":8,"note":60,"step":200},{"velocity":1,"length":8,"note":60,"step":264},{"velocity":1,"length":8,"note":60,"step":312},{"velocity":1,"length":8,"note":60,"step":360},{"velocity":1,"length":8,"note":60,"step":392},{"velocity":1,"length":8,"note":60,"step":456}],[{"velocity":1,"length":8,"note":60,"step":424},{"velocity":1,"length":8,"note":60,"step":440},{"velocity":1,"length":8,"note":60,"step":456}],[],[],[],[],[],[],[],[]],[[0,0,0.80000001192093,0.30000001192093],[0,0,0.80000001192093,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,2,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,0.10000000149012,0.40000000596046],[0,0,0.40000000596046,0.40000000596046],[0,0,0.60000002384186,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,0.30000001192093,0.40000000596046],[0,0,0.30000001192093,0.40000000596046]],[false,false,false,false,true,false,false,false,false,false,false,false,false,false,false,false],[[0,0],[0.5,0],[0,0],[0,0],[0,0],[0.40000000596046,0],[0,0],[0,0],[0,0],[0.5,0],[0,0],[0,0],[0,0],[0,0],[0,0],[0,0]],[0,0,0,-3,-3,-3,0,0,0,0,0,0,0,0,0,0],[1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1],[0,0,-4,0,0,0,0,0,0,0,0,0,0,0,0,0],["kick","snare","hihat","chord","bass","melody","perc","pewpew","","","","","","","",""]],[12,64],["nanobot567",{"millisecond":530,"weekday":3,"second":5,"minute":59,"hour":22,"year":2024,"day":19,"month":6}]]