Summary

We should have a grid handler, similar to what already exists for enc and key.

Why

More message sources and targets means more gear to connect to. The grid is a popular tool for use with the norns and opens up exciting plisp possibilities.

Also, a lens might not be needed, and the grid API is already nice, but a lens could "smooth out" or "pave over" differences between it and other hardware for the purposes of a lingua franca.

Considerations

• @ryanlaws does not own a grid and so could not test your code :( He does have an OG Launchpad Mini, though, if you happen to write a lens you want to test with it.

Summary

AST expression tables can already be generated from plisp sexprs stored in strings via plisp's expr_to_table function. However, the current implementation of expr-to-sexpr which converting in the other direction (AST to sexpr) lacks any kind of indentation, so while the sexprs it generates should be parseable by plisp, they are not human-readable.

Why?

Persistence - saving and sharing. This will be needed once the UI is ready to start manipulating expressions, in order to save them. It will also be needed in order to share them if and when we integrate e.g. norns.online sharing.

Considerations

• This may involve some trickery in nested tables.
• Associative tables (i.e. non-empty tables where #table == 0) should be changed to (: key1 value1 key2 value2 ...) format.
• There is a balance between reducing indentation and number of lines, avoiding long lines (I prefer an 80 char limit but I can be coaxed), and supporting a (yet unestablished) convention. This is mostly up to the implementer.
• Taking into account norns screen widths (via e.g. screen.text_extents()) would be ideal. This assumes the expressions will be displayed on the UI. This may not be the case and is completely irrelevant in the case of file persistence - only line length matters there. Could be pulled into a wishlist issue.

Summary

Add a debug mode that logs developer-centric information to the maiden/matron console.

Why

This can be useful for troubleshooting. Also it is fun and educational to see plisp work its magic on an AST maze.

Considerations

• There's a lot of commented-out junk logging already strewn throughout the code. These probably aren't best left as-is, but provide clues on decent places to log.

Summary

Add a scheduler to the app, and a way for expressions to plug into it.

Why

• There are scant sequencers not requiring a clock.
• MIDI delay/echo is cool.
• This could be nice for throttling/rate-limiting CCs... or not overwhelming a poor old TX81Z's MIDI buffer.

Considerations

• Here be dragons - at some point in every norns app's life, a clock (or 10) is added. And at some point soon after, that clock starts exhibiting inconsistencies.
• It seems that most folks have the best luck with monolithic clocks. From there, you can use ticks. Or you can use arbitrary delays, compensate for timing inconsistencies, and probably make a big mess. Whatever makes sense.
• This may require some work in code seemingly unrelated to, but affected by, the relentless onward march of the clock. It's pretty likely that there will be "rabbit holes" in computationally intensive processes where limits need to be placed, states need to be persisted, and things need to be resumed at a more opportune time.
• Scheduled tasks are basically threads. This introduces new problems to figure out: identifying, stopping, resuming, managing environments per-thread.

Summary

Provide a means for user scripts to expose configurable parameters. These could be e.g. MIDI channels, CC numbers, sequence lengths, timing values, etc. These could be stored in user configuration along with the loaded scripts, or set/changed on the fly.

Why

This would improve utility, discoverability, and accessibility of user scripts and make them feel more "modular".

Considerations

• The ability to set variables to an env already exists. This is effectively just metadata explicitly calling these out.
• Types might be neat but that would be a larger lift.

Summary

Configuration is currently saved in the repository. This completely defeats the purpose of configuration.

It is useful to have an example configuration so users can figure out how the heck to use pigeons. But the live configuration doesn't belong in the repository. Simply copying an example configuration to the real configuration path would do the job.

Accordingly, a .gitignore should include whatever the path of the live configuration the app uses, ends up being.

Why

Users will modify the configuration. Without a UI, this is an absolute necessity. When they do, Git will think they might want to commit to the repository. This is not necessarily true, and even if it was, they likely do not want to commit their configuration.

Configuration is separate from code for a reason, and after all, this is lisp - configuration is code!

Considerations

• Example configurations would be great. This could make the learning curve much shallower.
• Adding configuration path to .gitconfig is a must.
• Deleting the existing configuration (if it's still in there) is a must. Don't be shy about this!
• Feel free to mess with the configuration path as it stands today, just be sensible about it. There's a sweet spot between "clean" paths and deep nesting, and moving outside this sweet spot can be confusing/daunting. Try to stick to only one directory deep, if you can.

Summary

Expose the parameters declared in a defn.

Why

Related to #14, this improves utility, discoverability, and accessibility of user functions and makes them feel more "modular".

Considerations

• Part of the defn function already gathers these parameters from the definition (of course) so this would likely be a matter of creating a store of these parameters associated with the function names, rather than these residing within the closure of a function within its environment.
• It may be slightly tricky implementing the store. The easiest way is probably an associative table within the environment with a "magic" name with e.g. an underscore prefix that discourages changing the value elsewhere.
• This could be nice once a UI is in place to select the scripts. The values of the parameters could be set somewhere adjacent and maybe have other functions' output plugged into them.

Summary

MIDI ports for lensing and I/O are currently expressed as port IDs. These aren't even virtual IDs, they are low-level ALSA IDs. Let's not do this. Human-readable names are better.

Why

Most importantly, this is the kind of ephemeral, cryptic, machine-specific gobbledygook that means doodly squat to humans and runs directly counter to the pigeons design goals. We want to get (very) nerdy but this is the wrong kind of nerdy.

Secondly, these port numbers change all the time. Get real crazy with plugging and unplugging, restart your norns, and you'll find the port IDs have utterly changed. No bueno.

Considerations

• There is already (temporary/debugging) code in startup to enumerate the names of these ports. Adapting this code is probably the path of least resistance.
• The tokenizer (expr_to_table) treats all whitespace as a delimiter between tokens. I have considered tweaking the tokenizer to convert underscores to spaces for string tokens, and this would be a good use case. This would likely be just about the last tokenizing step. Naturally, anything accepting user input to select such a port would require the opposite conversion (space to underscore) for serialization to plisp.
• A plisp function to return a low-level port number based on a named port number would be fine, and probably the easiest approach based on where the ball lies today.

This is a whole can of worms. I haven't really begun to wrap my head around it. I think @tyleretters has a heck of a lot more ideas on this than I do.

Summary

Reconsider lenses: why they're good, what they could be, what they are and how that could better serve the idea.

Why

The implementation of lenses is a hacky mess right now. It does not do justice to the idea.

Considerations

• The mode functionality was very much tacked-on. I literally added it because of the 1.40 Octatrack OS that dropped on 2020-12-04.
• Nesting or groups could be nice here, both to group parameters within code and to imbue lensed parameters with their parents' traits. For example, all parameters with a range of 1-8 could be grouped together, and then this range only needs to be expressed once.
• Machine-readable metadata could be very useful for UI features that take advantage of lenses. This would include things like parameter types/names, or the range that already exists in the Octatrack lens.

Summary

We should have a helper (DSL) function to easily change the channel of an incoming MIDI message.

Why

This is a very common MIDI processing use case.

Considerations

• This may require binary arithmetic at the moment. No, I do not think this is great. If you're feeling motivated and want to build out more bytes -> env conversion, that would be lovely.
• It would be really cool if this took a list of channels so that, for example, multiple volume CCs could be changed at once, or a note could be played on several channels at a time. N.B. #5 could also help with this.
• There is a loose convention around using n and v for channel-bound or "channeled" messages like notes, CCs, and program changes, where n is e.g. note or number and v is e.g. velocity or value, but this implementation is incomplete.

Summary

@ngwese's sky library in the core norns platform library is supposed to achieve a lot of the same things pigeons does. It is a good idea to leverage the norns platform and use this. However, sky documentation is scarce-to-nonexistent and @ryanlaws is the first to admit that he has had much difficulty groking this library, even with the recommended tambla example source.

Why

We want to leverage the norns platform where it makes sense, and this seems like a great place to do it.

This could greatly reduce the footprint and responsibilities of the pigeons code, so we can focus on lispy, lensy, UI-y goodness.

The educational experience required in developing this understanding could prove valuable in precipitating documentation for sky itself in order to give back to the norns community.

Considerations

• It is possible that @ryanlaws is just stupid and this is actually super easy.
• It is also possible that some of the things that need updating to use sky are in very awkward, messy parts of the pigeons code.

Summary

As described in #2, MIDI are currently expressed as port IDs. Let's not. Human-readable names are nice. Platform-supported identifiers are just as good. Support the virtual ports (the 4 you select in the system menu).

Why

These are a well-established platform idiom and we should use them. The norns platform already provides a good UI for selecting these and that saves us work - we get port selection for free, users will "get it", and that's a UI problem we don't need to solve.

Considerations

• A plisp function to return a low-level port number based on a virtual port number would be fine, and probably the easiest approach based on where the ball lies today.
• Refactoring other functions to use virtual ports is also acceptable. Note that the ports identified in #2 do not necessarily overlap with these - there will only ever be 4 of these and there can be many more low-level ALSA ports.

Summary

We should have a function to express inclusive contiguous ranges like (1 2 3) or (37 38 39).

I'd suggest the name .. as this is used in norns's own SuperCollider and some other languages.

Why

This is a very common pattern, especially in MIDI processing. This is valuable for things like channels, note ranges, and indexing, as well as many other use cases. Lensing would make this even more useful for e.g. setting a row or block of LEDs at a time.

Considerations

• This would be valuable for lists of channels as suggested in #4

Summary

The Octatrack is the only MIDI lens at the moment. We need more.

Why

The more tools we lens, the more interesting this project becomes to folks who have MIDI problems to solve. Also, the more things we can connect.

This also helps road-test our DSLs and reveal gaps and improvement opportunities.

Considerations

• Volcas are cheap and cheery and have MIDI implementations that are a real sweet spot between simple and robust. These are a great starting point.
• Some of these could be pretty low-effort for making at least basic lenses: https://github.com/ryanlaws/gear-cc-lists-for-tidal
• For everything else, the MIDI implementation on the last few pages of the manual is often a good resource.