Roadmap for further development

[sourcebox]

I just want to put some notes here for further discussion, nothing set in stone.

• - A solution how to deal with SysEx messages has to be evaluated.

• - An example how to interface with other crates and how to send and receive SysEx will be put up.

• - We will do a release which is compatible with usb-device 0.3 after the SysEx support is tested.

• - The internal types need to be completed with the missing variants for System Common and System Realtime messages.

• There's hopefully a 0.4 release of usb-device at some point that removes the control-buffer-256 feature in favour of passing a dedicated control buffer to UsbDeviceBuilder::new(). That will solve the issues with large config descriptors. We do a new release right after usb-device 0.4 is out.

• MIDI 2.0 is something that comes up on the horizon. Should we try to integrate it or keep everything at 1.0 and start a new crate for it? If it's decided to be integrated, what about all the types it requires?

• Since having more than one jack is already supported, it would be nice to have string descriptors to have them labelled on the host.

• Using a builder pattern could possibly be helpful to manage those things like string descriptors.

[sourcebox]

I updated the list because #11 has been closed.

If we recommend the user to use an external types crate, we maybe should decide what to do with the ones that are now in. Possible options:

• Keep all of them in forever for backwards compatibility.
• Keep some of them in forever for backwards compatibility. If so, which ones?
• Mark them as deprecated, remove them in a later release to give users time to switch.
• Remove them as soon as interfacing with other libraries is implemented.

[btrepp]

I was thinking about this, it could be a good use-case for features?.
Eg say midi notes, the bare minimum needed is the u7 type.
User facing functions could take the type Into or return something that implements From. IIRC u7 is the full domain of a midi note.

This means the library is cut-down, minimal implementation, but the use can opt into a 'midi-types' feature that implements the traits from midi types. Users that wish to use external crates from note management either a) convert to/from in their own code, or b) add in a Pull request for the implementation of a new feature that allows people to 'seemlessly' use the external crate type.

As far as the change, a breaking change where they are dropped seems okay. I imagine this crate isn't used in a heap of things. So the affected parties are small.

Also I guess on types, everything in data is kinda 'if this type existed' we wouldn't need our own. I think the intent was always to have a more usbd-midi-data crate, with just the domain, and no real procedural logic. It just wasn't worth the effort at the time. If the data types in this crate are made into their own crate, other crates can implement the conversions aswell.

[sourcebox]

Regarding the SysEx processing, maybe the suggestion from @x37v mentioned in the original PR could be further investigated.

My initial idea here is to add an event() method to UsbMidiEventPacket that returns something like:

pub enum UsbMidiEvent<'a> {
  Regular(&'a [u8]),
  SysexStart(&'a [u8]),
  SysexContinue(&'a [u8]),
  SysexEnd(&'a [u8])
}

Because the enum variants contain &[u8] slices to the raw bytes, this would require to store them inside the packet as [u8; 4] instead of cable_number and message as it's done now. So it would be a breaking change because both fields are public. They could then be replaced by cable_number() and message() methods that create them on-the-fly.

For writing SysEx to the host, maybe a solution also based on iterators is possible. Not sure about that yet.

[laenzlinger]

I like the resolution to expose the regular midi raw data and let the application decide on the further midi processing.

[laenzlinger]

How can I use this crate to parse the raw packets into https://github.com/rust-midi/midi-types. Is there a recommended way?

[sourcebox]

How can I use this crate to parse the raw packets into https://github.com/rust-midi/midi-types. Is there a recommended way?

Unfortunately, there's no easy way to do it right now for two reasons:

• I had a look into the docs of the midi-types crate and did not find a way to construct a message from a raw &[u8] slice. That would be one requirement.
• usbd-midi currently doesn't offer a reliable way to access the underlying raw data beside than using &packet[1..]. That only works if you filter out certain packets by matching the code index number on packet[0] so that SysEx messages are discarded.

[x37v]

midi-types simply represents the midi, midi-convert parses and renders

[sourcebox]

midi-types simply represents the midi, midi-convert parses and renders

Thanks for the info, that solves at least part of the question. On our side, making things nicer does require a breaking change which is planned after a version compatible with still-not-released usb-device 0.4.

[laenzlinger]

What can be used to get packages? Would I use the MidiPacketBufferReader to get the &packet[1..] ? However that does not seem to expose the raw data. Or do I need to use the master branch for that until 0.4 is released?

[sourcebox]

What can be used to get packages? Would I use the MidiPacketBufferReader to get the &packet[1..] ? However that does not seem to expose the raw data. Or do I need to use the master branch for that until 0.4 is released?

It's something like this:

let mut midi_class = MidiClass::new(&usb_bus, 1, 1).unwrap();
let mut buffer = [0; 64];

if let Ok(size) = midi_class.read(&mut buffer) {
    for chunk in buffer[..size].chunks(4) {
        // Convert the chunk to message
    }
}

The chunk is &[u8] with a size of 4, so you can slice it as &chunk[1..]. But there is a problem with it: I doubt that midi-convert will accept all messages as 3 byte slices because their length is dependent on the type.

[sourcebox]

To improve the whole situation, I started some rework on the next branch. The packet itself now stores the raw message so that it can be accessed later. Please have a look at the ESP32-S3 example. It now converts the raw packets to midi-types messages and prints them on the console. Please note that SysEx is still not supported and requires more work. There's also a good amount of optimization to be done.

[laenzlinger]

Thank you very much @sourcebox . I applied your example to my application and it works well so far!

Now I need to figure out how to use it in the other direction. I want to render rust-midi/midi-types messages and send them to a usbd_midi cable.

[btrepp]

How can I use this crate to parse the raw packets into https://github.com/rust-midi/midi-types. Is there a recommended way?

Unfortunately, there's no easy way to do it right now for two reasons:

• I had a look into the docs of the midi-types crate and did not find a way to construct a message from a raw &[u8] slice. That would be one requirement.
• usbd-midi currently doesn't offer a reliable way to access the underlying raw data beside than using &packet[1..]. That only works if you filter out certain packets by matching the code index number on packet[0] so that SysEx messages are discarded.

So what parts are people interested in here? And why. A quick glance and we have from note to u8 and u7.

The data structures in data should be constructable from raw midi data as well. The io layers just use data as if is a public library.

There might not be examples, but I think most of the requirements here are doable, or perhaps just need slight changes to the code if a from/to definition was missing

Edit: Ah. Is this the external crate interacting with this one?. So more an issue there?

All the types in this crate should have from and try from, so should be creatable in code, from their primitive bytes, you would just have to handle errors if you gave it invalid data.

[sourcebox]

Now I need to figure out how to use it in the other direction. I want to render rust-midi/midi-types messages and send them to a usbd_midi cable.

I will have a look into that, but please give me a bit of time.

[sourcebox]

@laenzlinger I updated the example to send midi-types generated messages.