Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
stashymane committed Dec 2, 2020
1 parent 3ac0f92 commit cbc04db
Showing 1 changed file with 19 additions and 37 deletions.
56 changes: 19 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,64 +4,46 @@ Wrapper library for receiving and manipulating MIDI events.
**Currently in a pre-release stage, expect breaking changes until the first major release.**

## Features

* Type-safe MIDI events
* Event filtering and modification (in the order they are defined)
* Stream-like API
* MIDI as reactive streams (via RxJava)
* Minimal code required for listening
* Easy input & ~~output~~ _(coming soon)_

## Examples

### Opening device for reading inputs

```kotlin
val device = Device(MidiSystem.getMidiDeviceInfo()[1])
device.receivers += EventReceiver().addAction { println("Midi event received") }
Midifunk.deviceInfos[0].device.let {
it.open()
it.from.subscribe { /* you got a midi event! */ }
}
```

### Listening for note on/off events only
```kotlin
device.receivers += EventReceiver()
.filter { it is NoteData }
.addAction {
val e = it as NoteData
println("Note: ${e.note} ${if (it.noteStatus) "on" else "off"} | Velocity: ${it.velocity}")
}
```

### Modifying a CC event to be an on/off switch
```kotlin
var lastValue = -1
device.receivers += EventReceiver()
.filter { it is ControlData }
.modify {
val e = it as ControlData
if (e.value < 64)
e.value = 0
else
e.value = 127
it
}
.filter { (it as ControlData).value != lastValue }
.addAction {
val e = it as ControlData
lastValue = e.value
println("CC ${e.control} ${e.value == 127}")
}
device.from.filter { it is NoteData }.subscribe { /* you got a note on or off event! */ }
```

## Performance
Currently, Midifunk on average takes about 15 times longer to process MIDI inputs compared to pure Java.
Here is a rough sheet of how fast each take to process a certain amount of events on my machine (results via JMH):

Currently, Midifunk on average takes about 15 times longer to process MIDI inputs compared to pure Java. Here is a rough
sheet of how fast each take to process a certain amount of events on my machine (results via JMH):

| Benchmark | Mode | Cnt | Score | Error | Units |
| ------------------- | ----- | --- | ------- | -------- | ------ |
| JavaBench.bench | thrpt | 10 | 182.620 | ± 13.702 | ops/us |
| MidifunkBench.bench | thrpt | 10 | 12.979 | ± 0.721 | ops/us |
| MidifunkBench.bench | thrpt | 10 | 12.979 | ± 0.721 | ops/us |

My Launchkey Mini MK3 sends about 50 clock events per second on idle and about 300 events when actively twisting two CC knobs, so the performance penalty is negligible.
My Launchkey Mini MK3 sends about 50 clock events per second on idle and about 300 events when actively twisting two CC
knobs, so the performance penalty is negligible.
Regardless, I will still try to optimize the library more by the first major release.


## Contributing
Please follow [standard Kotlin code style guidelines][1], more thoroughly defined in JetBrains IDEs.
Other than that, feel free to submit pull requests - I will gladly review them.

Please follow [standard Kotlin code style guidelines][1], more thoroughly defined in JetBrains IDEs. Other than that,
feel free to submit pull requests - I will gladly review them.

[1]: https://kotlinlang.org/docs/reference/coding-conventions.html

0 comments on commit cbc04db

Please sign in to comment.