Update documentation

midi_io/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.0.7
+
+- Update Readme, no functional changes
+
 ## 1.0.6
 
 - Update link to Git repo

midi_io/README.md

@@ -1,15 +1,90 @@
-# midi_io
+# Midi IO
 
-A new flutter plugin project.
+Send and receive Midi Messages on Android, iOS, and MacOS!
+
+This plugin provides flutter bindings to interact with MIDI devices.
+The API design is draws heavily from the [Web MIDI](https://www.w3.org/TR/webmidi/) spec, providing a common API
+that wraps [Core Midi](https://developer.apple.com/documentation/coremidi/) on iOS and MacOS,
+and [androidx.media.midi](https://developer.android.com/reference/android/media/midi/package-summary) on Android.
+
+## Terminology
+
+In order to provide a unified, platform agnostic Flutter API, the plugin uses the following terms:
+
+- **Device** A device is Midi hardware or software that provides one or more Midi input and output ports. This plugin abstracts Devices away from you and simply provides a unified list of source and destination ports you can read from and write to. If you are coming from Web MIDI or Core MIDI this is regular practice, but Android has the Device abstraction, so this way of working may be new.
+
+- **Source** A Source is a port your app can listen to midi messages _from_. This is equivalent to a `MIDIInput` in WebMIDI.
+
+- **Destination** A Destination is a port your app can send messages _to_. This is equivalent to a `MIDIOutput` in WebMIDI.
 
 ## Getting Started
 
-This project is a starting point for a Flutter
-[plug-in package](https://flutter.dev/developing-packages/),
-a specialized package that includes platform-specific implementation code for
-Android and/or iOS.
+The `Midi` class is the main entry point into the MIDI system.
+
+```dart
+final midi = Midi():
+```
+
+## Listing Connected Ports
+
+You can get the list of connected sources and destinations like so:
+
+```dart
+final midi = Midi();
+
+final List<MidiSourcePort> sources = await midi.getSources();
+final List<MidiDestinationPort> destinations = await midi.getDestinations();
+```
+
+In addition, you can also listen to a stream of connection events that occur when devices are plugged in and unplugged:
+
+```dart
+await for (ConnectionEvent event in midi.onDevicesChanged) {
+  // process event
+}
+```
+
+Use cases for the `onDevicesChanged` stream include automatically connecting to a particular device, etc.
+
+## Sending Messages
+
+To send midi messages to an DestinationPort, first open it, then use the send method:
+
+```dart
+final List<MidiDestinationPort> destinations = await midi.getDestinations();
+final myDestination = destinations.first;
+await myDestination.open();
+
+// Key down on middle C
+await myDestination.send([0x90, 0x3C, 0x40]);
+```
+
+## Listening to Messages
+
+Listening to messages from a Midi Source requires opening and subscribing to the `messages` Stream:
+
+```dart
+final List<MidiSourcePort> sources = await midi.getSources();
+final mySource = sources.first;
+await mySource.open();
+
+await for (let message of mySource.messages) {
+  // process Midi message here
+}
+```
+
+### Filtering
+
+Since messages are sent as a Stream, you can filter midi messages using standard Dart techniques.
+
+For example, we provide a built in filter to hide MIDI clock messages:
+
+```dart
+await for (let message of mySource.messages.where(excludeClock)) {
+  // process Midi message here
+}
+```
 
-For help getting started with Flutter, view our
-[online documentation](https://flutter.dev/docs), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+## Contributing
 
+This plugin is a work in progress, and due to the scope of how MIDI can be used, and different platform specifics, There's plenty of room to help. Bug reports and Pull Requests are welcome!

midi_io/pubspec.yaml

@@ -1,6 +1,6 @@
 name: midi_io
 description: A new flutter plugin project.
-version: 1.0.6
+version: 1.0.7
 homepage: https://patchr.app
 repository: https://github.com/patchr-app/flutter_midi