3.3 / 4.0 plans - Githubissues

-------- Upcoming Priorities -------- -- 3.5 Stuff --

[ ] Tuning only shows tuning of current note and interval of last two notes when connected to Direct, which is confusing; want to be able to see that information even if only connected to, say, Nostalgic
[ ] if you put a forward-slash in a Piano name, it seems to cause a crash when you save/load the Gallery; should protect for that.
[ ] Jascha: I just re-created my problem in the simplest possible patch, so maybe you can just try this out: Keyboard 1 (all notes save A0) -> Synchronic in "synchronic" mode in the target list, and the Synchronic set to repeat everything 100 times (annoying!);Keyboard 2 (only A0) -> Synchronic, set to "clear" mode in the target list; A0 doesn't clear any more! I have old patches where this worked... “Synchronic Target Triggers: Clear” looks like it just isn’t responding to Note-Ons - Note-Off works, and by extension “Both” also works.
[x] Bleondronic send seems to be post Main Gain, in Direct, possibly others. should be able to send to Blendronic while having the direct out quiet or silenced
[ ] CRASH: Spring tuning, turn off "sets weights," turn on "highest", play C7 chord ascending on C4, release keys=>boom
[ ] BUG: noteOff is not working properly in Resonance, for Held notes
[ ] change default Hammer gain in Direct to -12; too loud as is
[ ] velocity sensitivity for spring tuning: higher velocity leading to more intense oscillation before convergence, for example
[ ] mod increment and other sliders have blue status bar and should not
[ ] mod a/b indicator is not showing when using plugin (jascha)
[ ] when I'm editing in a DAW and I have the BitKlavier VST window open, I'd love to be able to collapse the patch part of it and just see the keyboard so I can tuck it at the bottom of my work area and still have access to the all-important "stop everything" safety keys (jn).
[ ] Jascha Mod request: "I was just thinking: yes, I can set up a Modification to set the volume of Nostalgic (or whatever) to -inf dB, with an alternate to set it back to 0 dB, but it would be visually nicer if there were on/off modes - with "off" making the graphic dimmer or grey or something.A further advantage: by switching volume from -inf to audible, you can hear the tail end of any effects that were happening while the volume was down. If I wanted to play a bunch of stuff and then "reveal" an effect, triggering a volume-up would also reveal all the noise the effect was making behind the scenes, whereas an "on" mode would simply start processing at that point..."
[ ] Mod curiosity: if you have two mods connected to a single preparation, both modding the same parameter (for instance, one modding it to increase it, the other to decrease it), they work independently, so if you increase it a few times to, say, X, and then decrease it to, say, Y, and then increase again, it will increase from X, not from Y. this is counterintuitive, though maybe it has viritues in that the mods can exist in parallel; I think we should revisit this though.
[ ] Jascha synchronic Mod request: "Let's say I've got a Metronome that can be set to different speeds by different keys. Let's say I want some other key to simply increment the tempo by 1 - I can't find a way to do that without also defining a starting tempo for the Modification. Is there a way to have abstract increments/decrements or, if not, could there be?"
[ ] The Reset doesn't put the Mod back to A (for toggling mods), which should maybe be the default?
[ ] infinite mode in Synchronic, to repeat indefinitely
[ ] "cluster Max" in Nostalgic (like in Synchronic); Jascha request
[ ] Maybe: add a little circle at the point where a line connects with a box as visual confirmation that that's a connection point? Lines that run long distances behind other boxes can be confusing. (Jascha).
[ ] do we need Undertow and Wave Blendronic send volume sliders now that Nostalgic is properly sending the reverse notes to Blendronic? to reproduce what the Machines for Listening were doing? or maybe not?
[ ] anchor tuning weirdness: if the anchor scale is non-ET, it doesn;t always behave as expected
[ ] the tuningOffset mod is a bit of a hack right now, due to the fact that it is stored as fractional MIDI offsets (internally and in all the saved galleries) but displayed as cents, and the Moddable doesn't handle this well unless with a hack. maybe it's ok, but a bit unfortunate.
[ ] enable player to play in sequences to Synchronic transpositions?
[ ] create some way to transpose Absolute tunings; even a +/- button that simply shifts everything up/down a key

-- New Features 4.0? --
[ ] VST hosting/routing
[ ] velocity dependent parameters? for instance, have the Release value in Direct change based on velocity for, say, a cymbal sample
[ ] audio input; start with blendrónic
[ ] create electronic drum set interface! generalizable from that (could just include a pad or a pedal), and re-configurable, so the user can build a virtual interface that matches their physical interface.
[ ] related: BopPad/MPE support would be a good case to consider.
[ ] HEJI calculator? display HEJI accidental based on last note played and tuning system/fundamental. Some starting points here: https://www.plainsound.org/. would need new panel in Tuning (dt)
[ ] Resonance variation (or new prep) which models stopped harmonics; touch string at particular harmonic, strike key. Could be interesting...
[ ] Stereo? For instance, two Synchronics, one panned left, one right...
[ ] make the various preparations work as VST/AU plugins, independently
[ ] Synchronic: lots more possibilities (Thesys, https://sugar-bytes.de/thesys, has some nice features to consider) -- have pitches by transposed (as they are now, relative to played pitch) or fixed -- be able to play pitches in via keyboard -- set ranges within parameter fields (so, select pitches 3-7 to cycle through) -- forward, backward, back and forth modes -- ADSR fields each with their own multi sliders, as opposed to being hidden away the way they are now. -- randomization ranges for all multi slider parameters (including discrete or continuous options) -- scale filters, for when playing or hand drawing patterns into multi slider -- velocity => parameter control; for instance, velocity changes depth of randomness in a particular parameter

[ ] new "flowchart" of Piano/Gallery structure (dp)
[ ] randomness ranges in multi slider? so, for instance, in Synchronic could specify a range of values that would be randomly chosen from, with the option of the values being limited to integers. Could also have multiple values (like in the transposition multi slider) that it chooses from, perhaps random-without-replacement
[ ] other tuning additions inspired by https://isartum.net, and this article ?
[ ] una corda pedal? perhaps for sample-library switching? (Blanchet lute-stop switch could be a useful example)
[ ] half-pedaling; could do some combination of adjusting the release time and EQ to emulate?
[ ] further optimization options for Resonance: 1) allow user to toggle on/off whether new note needs to be louder than currently playing note (same note); this is currently commented out in the code so it's just a matter of adding a toggle to the preparation. 2) allow user to specify max ring-time? sometimes we get a really big build-up of tails, that are basically silent (other than room noise, which builds up), playing (especially with the bK Grand and its long tails), and it can cause clicks and so on.

-- 3.4 Stuff --
[x] Next new feature: Piano Iterator, and possibly Piano Navigator (think 120bpm and all the presets). this might be useful: https://github.com/getdunne/juce-draggableListBox
[x] BUG: Synchronic hold min/max time seems to be broken when Synchronic is in Last Note-Off mode. Set the min to anything above 0, and Synchronic just won't work
[x] figure out why the sustain pedal is always triggering sounds now; there should be an option or volume control for this, if we have it.
[x] create a "ignore noteOff" toggle in Keymap. for infinite sustain (Max V request)
[x] most of the slider text boxes show some messy e-15 number instead of '0'; should clean that up
[x] Global sample setting isn't saving with gallery

-- 3.3 Stuff --
[x] Win build testing? (dp, with some Win users, after we finish the 3.3 updates)
[x] iOS (dp, possible to get setup to do this still?)
[x] correct blue status bar visibility in sliders everywhere (for instance, Direct sliders). just need to set displaySlider to false for each (dt)
[x] when resizing, the compressor menus (Gain Reduction, and preset) disappear (dp)
[x] bug where sometimes old galleries open and the Keymaps don't have "Default MIDI Input" selected. (dp)
[x] sometimes the custom Tuning values become .001 what they should be. need to work up a repeatable example to fix (dt will try to work up example, then either dt or dp will fix)
[x] Example Gallery 17 error: This loaded for me (Jascha) with a tuning of "None" rather than "Adaptive 1". An easy fix, but kind of a bummer for people who read the note about hearing D-E-F# spiraling upwards and then... not hearing that. (dt)
[x] Mod smooth times bug: caps at 2000 for some reason, with Direct anyhow (dp)
[x] Nostalgic does not feed Blendronic unless Undertow > 0, which doesn't make sense (Jascha note, from 1.11.23) (dp)
[x] with Nostalgic and at least some Soundfonts (jrhodes, for instance), notes held for a long time (several seconds) won't play in reverse, suggesting a max delay time issue (dp)
[x] blue status bar for Hold Time in Nostalgic doesn't scale properly for values other than the default
[x] also with Nostalgic, for some reason velocity does not affect loudness! (dp)
[x] Nostalgic manual entry needs to be updated, since the Gain slider no longer exists, and there is just the dB slider (dt)
[x] This is maybe against the spirit of BitKlavier, since people should be listening and not looking at screens, but I'd love some visual cue for a Modification set in Alternating mode as to which mode it's in... (jascha) Regular Mod = normal triangle Alternating Mod = has a letter A or B inside it that swap out depending on state
[x] ADSR release set to 5000 makes some of the steel pan notes just silent; some kind of bug (dp); actually, applies to all samples. with Heavy, set the Release time to 50000 and basically none of the notes will sound. if the Release time is > the sample length, it doesn't play, is the problem I think.
[x] when there are two folders with the same name, one of them in a subfolder, the gallery loading/saving doesn't work properly (dp)
[x] when a Keymap is set to harmonize (so that, say, F#5 comes out as C5), that Keymap will no longer trigger a Modification that it is connected to, which seems odd (Jascha discovered this). It's easy to work around, but probably shouldn't need to. yeah this is confusing. (dp)
[x] scrollable construction area (dp)
[x] Blendronic will continue to make sound after closing Gallery and opening a new Gallery. we want that to be possible when changing Pianos within a Gallery, but NOT when closing a gallery
[x] renaming a Gallery .xml file in the Finder doesnt' work correctly, as i think the name is also internal to the file; something that should be addressed so we can rename files in the Finder without causing confusion (dp)
[x] when creating a Linked Copy of a Piano, all the comment boxes resize in annoying ways. Does not happen when Duplicating a Piano (dp)
[ ] spring tuning/MTS: be able to run without ANY audio? at the moment needs at least Direct
[ ] some strangeness in Resonance, with thumping, hammer release sounds, and so on... (dt)
[x] figure out how to constrain range in a smart way. Used to be constrained by piano range, but I think we changed that with Resonance, allowing higher pitches, but now with Pascal's piece, we're getting unwanted high pitches in Synchronic. So, perhaps in preparations that transpose, have some kind of option to constrain? or automatically constrain for those, but not Resonance?
[x] in Synchronic, none of the singleSlider blue status bars are showing. displaySlider
[ ] new Looper preparation type? Tepfer 4 inspired. (“Loopic”?)
[ ] Keymap "Keys" menu: add "transpose" feature, which will simply move the set keys in the bottom keyboard up/down by a specified interval. not sure what the best design approach is. I suppose it could just be an int box (not the menu) that is 0 by default.
[ ] possibly implement Sethare's "Adaptun" algorithm
[ ] basic adaptive tempo additions: exponential MA, beat-level identification...
[ ] MPE support
[ ] delay times based on velocity? "THE PIANO ACTION AS THE PERFORMER’S INTERFACE: TIMING PROPERTIES, DYNAMIC BEHAVIOUR AND THE PERFORMER’S POSSIBILITIES" paper. Could be quite easy, and potentially interesting.

-------- 3.2 Priorities -------- -- Tuning Stuff --
[x] Oddsound integration: https://oddsound.com . both "server" and "client"? which might allow for spring tuning in other instruments (dp)
[x] add "Resources paths:" option to Preferences, so people can put their galleries and so on elsewhere (for instance, I would like to be able to put the galleries in a Dropbox folder, so it's shared across my devices)
[x] add compressor and limiter after eq; JUCE has both https://docs.juce.com/master/classdsp_1_1Compressor.html, https://docs.juce.com/master/classdsp_1_1Limiter.html. would be interesting to add these to individual preparations (so, say, Synchronic would have extra panels for each, applied just to that Synchronic) but I think it would be tricky to implement, since they all share a synthesizer (Blendronic works around this, but not in a way that would generalize easily if I remember correctly)

-------- 3.1 Priorities --------
[x] when quitting or pressing x, prompt user to save gallery if it is dirty
[x] keep items selected after copy/paste; When I make a selection of several objects and do a copy/paste on them, the duplicated land mostly on top of the old ones, which is expected, but they don't stay selected, which feels unnatural. It feels like after a paste of a group of objects I should be able to grab them en masse and move them to a new location... (from Jascha)
[x] Resonance doesn't work fully with Soundfonts, not sure why. Some resonances seem to play, but very sparse and quiet.
[x] Blendronic send volume slider is not resizing properly in Direct, maybe elsewhere as well
[x] when a Piano is duplicated, Comment contents are not and should be
[x] Scala format reading (https://surge-synth-team.org/tuning-library/ and https://surge-synth-team.org/tuning-workbench-synth/ this JUCE example looks like it might be nice to integrate directly into bK, minus the synth part (unless we want to think about doing some synthesis in bK!)
[x] A connection between Resonance and Blendronic will be broken on save [bug]
[x] Resonance new target modes: Add Sympathetic String, Ring Sympathetic Strings (both on by default) [new feature]
[x] Keymap: add “toggle” mode, where noteOff is ignored, and noteOn will act as noteOff for on notes; when combined with the new Resonance target modes, this will allow the use of one Keymap to add sympathetic strings and leave them there, and then "ring" them from another Keymap (Hardanger inspired) [new feature]
[x] new panel in Resonance that displays: 1) currently held keys, and 2) currently resonant keys. Probably one keyboard display for each. [new feature]
[x] Save bug: sometimes a gallery stored in a subfolder of Galleries gets saved in the top level instead of the subfolder, perhaps caused by undo. Reproducible: create new gallery in subfolder. Quit and Reopen bK. Make a change, and save it; should still save in subfolder. Now make a change and then undo the change using command-Z, then save; will save in top-level Gallery folder instead of subfolder
[x] fixed bug where Resonance wasn't handling Max Sympathetic Strings properly
[x] - [x] sostenuto pedal support
[x] ignore sustain pedal option in Keymap does not save properly
[x] sostenuto mode in Keymap (making sustain pedal behave like sostenuto pedal); could be tricky!
[x] optimize Resonance "add"; it causes glitches far too easily, perhaps because of voice stealing?
[x] importing a pre-saved preparation in Resonance causes crash
[x] in Resonance, choosing a pre-existing setting (already in the Gallery, so from the top-left menu within the Resonance pane) doesn't seem to do anything; settings don't change, and re-opening the pane shows it reverting to the prior selection
[x] Catalina issues: code signing of plugins, notarizing
[x] Resonance Mods don't all work correctly. try modifying the defined overtone structure; some bugs there. and then once you have a Mod, it doesn't actually cause the Mod to happen unless you fiddle with it

-------- 3.0 Priorities --------
[x] new Resonance preparation
[x] built-in EQ unit on the output side? would be use for standalone, when working with different speaker types and so on. JUCE has some filter stuff: https://docs.juce.com/master/structdsp_1_1IIR_1_1Coefficients.html#details, and maybe there are some examples for generating nice UI elements for it too. could be some complications with signal flow, though maybe we figured that out already with Blendrónic?
[x] Mod smoothing of anchor stiffness in spring tuning does not seem to work; just mods without smoothing
[x] check implementation of release resonance sample playback; how is the gain set? duration of played note should be a factor, or put another way: time between noteOn and noteOff should impact the release resonance loudness, along with attack velocity
[x] pressing "command Q" adds a Comment, unless you click on the top border first; I don't think it used to do this, and it's confusing
[x] Steinway sample sets #138 (release the images one by one. also, release the full Yamaha set with 3.0)
[x] steel pan sample library as well
[x] website addition for bitKlavier Grand
[x] documentation update
[x] mail chimp announcement
[x] iOS

-------- 2.9 Priorities --------

[x] updates of current sample implementation, primarily for velocity handling
[x] direct from disk streaming option? MemoryMappedAudioFormatReader class, and also some info from Jules here: https://forum.juce.com/t/memorymappedfile-questions/19927/7
[x] flexible resource path, so users can put the samples folder and so on where they want, instead of it being hard-wired in the Applications folder
[x] modify original Salamander/Yamaha library so naming scheme matches ours; release with 2.9 as example that can be used with direct-from-disk streaming
[x] velocity curves in Keymap, including velocity inversion (so high velocity => soft, etc...), reducing dynamic range to focus on subsets of the velocities, etc... also basic balance curves (many piano samplers have a way to balance low/high velocities across the range of the keyboard)
[x] BUG in Blendronic: the close input/output targets don't seem to work; try Examples:37. Blendronic 5
[x] update documentation

-------- Bugs --------
[ ] a single Reset object can be connected to multiple preparations, but won't work on any of them. Reset only works if a single Reset is connected to a single preparation; this is fine, but with this behavior we shouldn't be able to actually connect a Reset to more than one preparation (causes confusion). not able to reproduce this, a single Reset seems to work fine for multiple preparations
[ ] clicking a bkslider component in mod editor view then using the ui keyboard to play a note results in a stuck note
[ ] Blendronic input gain slider should dim when not attached to Blendronic?
[ ] in Synchronic, MIDI Output destination is not saved with Gallery

-------- Boring but Important Things --------

[ ] general UI cleanup
[ ] playing with large mappings in the harmonizer and a looping soundfont can run into performance problems - should look into optimizing processSoundfontLoop and check other cases
[ ] remove ModalLoop calls
[ ] code documentation
[ ] remove dead branches
[ ] remove "Open (legacy)" from Gallery menu?
[x] add keystroke for All Off (and a way to trigger it with a Keymap?) add hotkey for All Off?
[x] option to turn off keystrokes, for adding preparations
[x] make default buffer size in standalone 128? i think it defaults to 512, which is perceptibly slow
[x] increase the number of subfolders that can be autoloaded into Galleries and Preparations menus
[x] ability to reorder Pianos in Piano menu?
[x] unlinked copy in Piano menu

-------- Big Ideas --------

new Looper preparation type? dunno... Tepfer #4
explore approaches to adaptive tempo
explore whether to pursue scripting
explore possible OSC/network in/out protocol (possibly also Ableton Link) -- noteOn/Off messages, Synchronic, Nostalgic start/reverse, Blendronic delay time changes, etc...
spectral preparation/filters?
audio input?
internal synthesis? perhaps based on Surge: https://surge-synthesizer.github.io, or is VCV rack open source?
MPE

-------- Medium to Small Ideas --------

[ ] smoothing of Mods; specify a time for a mod to take place over (cross fades)
[ ] Mod option to alternate with reset
[ ] Mod/Piano Switch extensions: "have a threshold set for certain number and set of input pitches required to trigger a change? For example, if I only wanted [CEG] played together simultaneously to trigger a tuning change, could I do that?" from Noah. Could have "cluster min" and "threshold" in Mod and Piano, which indicates how many notes would have to be received within a time window to actually trigger the Mod/Piano.
[ ] Mod SampleSet
[ ] incremental Mods? "every time “every time I hit C5, the tempo parameter in the Metronome preparation increases by 5 bpm...”) (Chris D idea)
[x] add keystroke for All Off
[ ] add more Nostalgic targets. Ideas: Hold, could act almost like a pedal but only for timing how long Nostalgic notes are held
[ ] Customize window menu options, appearance, and layout
[ ] Spring Tuning: retain pedal sustain notes? currently it does not. an option?
[ ] possible for inputs to Blendrónic to be pre-gain? for example: can i set the gain of a Nostalgic preparation to 0, but still have a connected Blendrónic get its signal? if it's easy to do, would be good. can't remember how the signal flow works...
[ ] add "ignore pedal" toggle option to Keymap. some situations might want to ignore the pedal; for instance, Spring Tuning might want to factor in only depressed notes, while at the same time Direct might want to sustain with the pedal.
[x] multiple sample sets open simultaneously

-------- Fixed Bugs --------

[x] "delete" in Preparation Action menu crashes.
[x] "rotate layers" in Keymap => Synchronic does not seem to work, and can cause crashes
[x] when adding a Keymap in DAW, the "default input" does not get set; so, when saving and then reopening in standalone, it's confusing, because things don't work as expected. probably fixed... YES, CONFIRMED
[x] pitchbend seems to be broken again; does nothing was broken by the addition midi input selection, fixed but currently no differentiation between midi sources, so all pitch bend messages apply to everything
[x] SoundFont looping pretty often has clicks; try the jRhodes3b piano. it's possible it's a problem in the SoundFont itself, and not our problem, but i'm not sure. I think this may mostly be an issue in non-ET tunings, where the interpolation might mean the loop points aren't as expected. not sure what to do about that!
[x] it seems that really long Nostalgic notes in note-length mode no longer play; if you hold a note for a really long time, it never actually plays, when it should.
[x] As a plugin, closing the UI with a menu open will not dismiss the menu and can sometimes cause a crash. crashes fixed but some menus can still hang (ModalLoop issue?)
[x] need to address Nostalgic crossfade issues for SoundFonts; this is fixed for the built-in, so should be easy
[x] fundamental in Tuning doesn't show the actual value in the keyboard display on opening the TuningVC
[x] when importing a Synchronic preparation with more than 12 values in a multi slider, only the first 12 will import; in general the multislidres are buggy with more than 12 values, when reloading, reopening.
[x] hard crash in Logic when opening the bK UI a 2nd time; crashes as soon as you mouse-over the bK UI
[x] ADSR release doesn't work for SoundFonts with looping this might be fixed, not sure if i've checked every case. dt:appears to be fixed!
[x] Synchronic: ADSR slider UI doesn't initialize properly (first one isn't yellow) when VC is initially opened; moving to another tab and then back gets it there, but shouldn't have to do that. minor, maybe ignore

-------- ToDo for 2.8 release -------- BUGS

[x] Synchronic Mod: "num layers" slider doesn't highlight when moved
[x] Fix Mods for Tuning; sliders misbehave, making it almost impossible
[x] when plugins autoload Galleries, they sometimes don't behave properly; example: Preludes 1 and 2 in Dorico, Synchronic stuff just doesn't play. Loading a different gallery and then re-loading, then the galleries work fine. Some kind of initialization issue, perhaps with Mods? They are fine with standalone, and the Synchronic preps appear to be getting note info from Keymap, as they UI shows activity, but no sound. Not seeing this in Logic, however. Another example: in Prelude 3, some of the Synchronics seem to load incompletely, and when you re-quit Dorico and re-load Prelude 3, it will be different ones that load incompletely; I'm seeing this in Logic too, and also in the standalone (the gallery loads fine in 2.7b1)

TESTING

[x] test plugin formats, old pieces
[x] test iOS
[x] test Windows

DOCUMENTATION

[x] update documentation and release notes
[x] Mailchimp announcement
[x] new installer

COMPLETE

[x] create some new example pianos: -- Spring Tuning default -- Spring Tuning drift -- Dynamic Modifications -- Harmonizer
[x] have Spring Tuning automatically load to AutoSpringTune settings
[x] Spring Tuning bugs; not initializing Rate properly, and "sets weights" toggle visibility isn't working right; "drag" slider is misbehaving
[x] further testing of new Mod behaviors
[x] clarifying new Mod functionality; ToolTip, possibly a button. some things in place, not sure if enough
[x] Harmonizer layout on iPhones?
[x] Blendronic gain slider UI placement -- for Direct, move ADSR sliders to panel with Blendronic slider, make Transposition slider full width -- for Synchronic, put Blendronic slider on panel with Targets, below -- for Nostalgic, put Blendronic slider on panel with ADSRs, below
[x] iOS: make sure SoundFont menus are behind preparation panels
[x] reorder Keymap options so Sustain Pedal options are consecutive
[x] Blendronic input pre-gain from attached preparations; so prep can be muted but still fed into Blendronic
[x] Keymap extensions: "harmonizer" possibilities; also, "mirror", "trap", and similar behaviors.
[x] undo
[x] add velocity filtering to Direct
[x] Mod additions (smoothing, alternate, thresholding, sample-set, incrementing/decrementing, all as described below)

Princeton-CDH / bitKlavier

3.3 / 4.0 plans #135

[ ] create some way to transpose Absolute tunings; even a +/- button that simply shifts everything up/down a key

[x] Global sample setting isn't saving with gallery

[x] when creating a Linked Copy of a Piano, all the comment boxes resize in annoying ways. Does not happen when Duplicating a Piano (dp)

[x] in Synchronic, none of the singleSlider blue status bars are showing. displaySlider

[ ] delay times based on velocity? "THE PIANO ACTION AS THE PERFORMER’S INTERFACE: TIMING PROPERTIES, DYNAMIC BEHAVIOUR AND THE PERFORMER’S POSSIBILITIES" paper. Could be quite easy, and potentially interesting.

[x] Resonance Mods don't all work correctly. try modifying the defined overtone structure; some bugs there. and then once you have a Mod, it doesn't actually cause the Mod to happen unless you fiddle with it

[x] iOS

[x] update documentation