[docs] Doc & test improvements

book/src/SUMMARY.md

@@ -20,6 +20,7 @@
   - [External polling](./polling.md)
   - [Timestamping](./timestamping.md)
 - [Queue vs callbacks](./queue.md)
+- [Computer keyboard input](./keyboard.md)
 
 # Reference
 - [Backends](./backends.md)

book/src/backends.md

@@ -11,7 +11,7 @@ or because it has not been implemented yet.
 |               | ALSA Raw | ALSA Seq | PipeWire |
 |---------------|----------|----------|----------|
 | MIDI 1        | Yes      | Yes      | Yes      |
-| MIDI 2        | Yes      | Yes      | No       |
+| MIDI 2        | Yes      | Yes      | N/A      |
 | Virtual ports | N/A      | Yes      | Yes      |
 | Observer      | Yes      | Yes      | Yes      |
 | Scheduling    | No       | No       | No       |
@@ -32,9 +32,9 @@ without preventing application loading if the end user does not use it.
 |               | WinMM | UWP | WinMIDI |
 |---------------|-------|-----|---------|
 | MIDI 1        | Yes   | Yes | No      |
-| MIDI 2        | N/A   | N/A | No      |
+| MIDI 2        | N/A   | N/A | Yes     |
 | Virtual ports | N/A   | No  | No      |
-| Observer      | Yes   | Yes | No      |
+| Observer      | Yes   | Yes | Yes     |
 | Scheduling    | No    | No  | No      |
 
 ## Mac & iOS
@@ -62,7 +62,7 @@ without preventing application loading if the end user does not use it.
 |               | JACK |
 |---------------|------|
 | MIDI 1        | Yes  |
-| MIDI 2        | No   |
+| MIDI 2        | N/A  |
 | Virtual ports | Yes  |
 | Observer      | Yes  |
 | Scheduling    | No   |

book/src/compiling.md

@@ -53,4 +53,4 @@ e.g. `-DCMAKE_OSX_DEPLOYMENT_TARGET=11` or more recent needs to be passed to CMa
 
 ## Advanced features
 
-- Ability to set a fixed message size for zero-allocation scenarios, with -DLIBREMIDI_SLIM_MESSAGE=<NBytes> (in CMake or directly to the compiler)
+- For MIDI 1: ability to set a fixed message size upper-bound for zero-allocation scenarios, with `-DLIBREMIDI_SLIM_MESSAGE=<NBytes>` (in CMake or directly to the compiler)

book/src/configuration.md

@@ -2,8 +2,41 @@
 
 The `midi_in`, `midi_out` and `midi_observer` objects are configured through a `input_configuration` (resp. `output_`, etc.) object passed in argument to the constructor.
 
+
+Example:
+
+```cpp
+#include <libremidi/configurations.hpp>
+
+...
+
+libremidi::midi_in in{
+    libremidi::input_configuration{
+      .on_message = ...
+    , .ignore_sysex = false
+    , .ignore_sensing = true
+    }
+};
+```
+
 ## Custom back-end configuration
 
 Additionnally, each back-end supports back-end specific configuration options, to enable users to tap into advanced features of a given API while retaining the general C++ abstraction.
 
 For instance, this enables to set output buffer sizes, chunking parameters, etc. for back-ends which support the feature.
+
+
+```cpp
+#include <libremidi/backends.hpp>
+
+...
+
+libremidi::midi_in in{
+    libremidi::input_configuration{
+      .on_message = ...
+    },
+    libremidi::pipewire_input_configuration{
+      .client_name = "My app"
+    }
+};
+```

book/src/context-sharing.md

@@ -39,6 +39,8 @@ libremidi::midi_out out{
 };
 ```
 
+In that case, note that the `obs` has ownership of for instance the JACK context object: it must outlive `in` and `out`.
+
 The relevant examples are:
 - `coremidi_share.cpp` for a complete example for CoreMIDI.
 - `jack_share.cpp` for a complete example for JACK.

book/src/foreword.md

@@ -27,3 +27,4 @@ It also features some new & improved backends:
 - Windows UWP.
 - WebMIDI in Emscripten.
 - JACK support on all platforms where it is available.
+- Computer keyboard input.

book/src/keyboard.md

@@ -0,0 +1,32 @@
+# Computer keyboard input
+
+This backend allwos to use the computer keys to play MIDI.
+The backend does not directly read the key events as this would require making the library much more complex.
+Instead, it provides a callback that you can plug into your favourite GUI toolkit to process scan codes.
+
+The mapping is customizable. By default:
+
+```
+ ,---,---,---,---,---,---,---,---,---,---,---,---,---,-------,
+ | V0| V1| V2| V3| V4| V5| V6| V7| V8| V9|V10|V11|V12| <-    |
+ |---'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-----|
+ | ->| |   | C#| D#|   | F#| G#| A#|   | C#| D#|   | F#|     |
+ |-----',--',--',--',--',--',--',--',--',--',--',--',--'|    |
+ | Caps | C | D | E | F | G | A | B | C | D | E | F | G |    |
+ |----,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'---'----|
+ | -^ |   | O-| O+| V-| V+|   |   |   |   |   |   |   ----^  |
+ |----'-,-',--'--,'---'---'---'---'---'---'-,-'---',--,------|
+ | ctrl |  | alt |                          |altgr |  | ctrl |
+ '------'  '-----'--------------------------'------'  '------'
+```
+
+Where V0 to V12 set the velocity between 0 and 127 in steps of ~10, O- / O+ increase or decrease the octave and V- / V+ increase or decrease the velocity by 10.
+
+
+Example:
+```
+#include <libremidi/backends/keyboard/config.hpp>
+
+libremidi::kbd_input_configuration api_conf;
+api_conf.set_input_scancode_callbacks(
+[] )

book/src/queue.md

@@ -3,3 +3,7 @@
 The old queued input mechanism present in RtMidi and previous versions of the library has been moved out of the code as it can be built entirely on the callback mechanism and integrated with the user application's event processing queue instead.
 
 A basic example is provided in `qmidiin.cpp`.
+
+We recommend if possible to instead use an asynchronous runtime in order to keep an imperative behaviour while benefiting from the non-blocking properties of async programming.
+
+An example based on C++20 coroutines with Boost.Cobalt is provided in `coroutines.cpp`.

tests/unit/midi_in.cpp

@@ -1,15 +1,98 @@
 #include "../include_catch.hpp"
 
+#include <libremidi/backends/keyboard/config.hpp>
 #include <libremidi/libremidi.hpp>
 
 #include <chrono>
 #include <thread>
 
 #if __has_include(<jack/jack.h>)
+  #include <libremidi/backends/jack/config.hpp>
+
   #include <jack/jack.h>
 #endif
 
-#include <libremidi/backends/jack/config.hpp>
+TEST_CASE("creation", "[midi_in]")
+{
+  GIVEN("A default midi input")
+  {
+    libremidi::midi_in in(libremidi::input_configuration{.on_message = [](auto) {}});
+    THEN("created with the default MIDI 1 api for the platform")
+    {
+      REQUIRE(in.get_current_api() == libremidi::midi1::default_api());
+    }
+  }
+
+  GIVEN("A default ump input")
+  {
+    libremidi::ump_input_configuration conf{.on_message = [](auto) {}};
+    libremidi::midi_in in(conf);
+    THEN("created with the default MIDI 2 api for the platform")
+    {
+      REQUIRE(in.get_current_api() == libremidi::midi2::default_api());
+    }
+  }
+
+  GIVEN("A midi input with an explicitly unspecified API")
+  {
+    libremidi::midi_in in(
+        libremidi::input_configuration{.on_message = [](auto) {}}, libremidi::API::UNSPECIFIED);
+    THEN("created with the default api")
+    {
+      REQUIRE(in.get_current_api() == libremidi::midi1::default_api());
+    }
+  }
+
+  GIVEN("A midi input with an empty API")
+  {
+    libremidi::midi_in in(libremidi::input_configuration{.on_message = [](auto) {}}, std::any{});
+    THEN("created with defaultapi")
+    {
+      REQUIRE(in.get_current_api() == libremidi::midi1::default_api());
+    }
+  }
+  GIVEN("A midi input with an explicit API")
+  {
+    libremidi::midi_in in(
+        libremidi::input_configuration{.on_message = [](auto) {}}, libremidi::API::KEYBOARD);
+    THEN("created with that api")
+    {
+      REQUIRE(in.get_current_api() == libremidi::API::KEYBOARD);
+    }
+  }
+
+  GIVEN("A midi input with a wrong API")
+  {
+    libremidi::midi_in in(libremidi::input_configuration{.on_message = [](auto) {}}, float(1.23f));
+    THEN("created with dummy api")
+    {
+      REQUIRE(in.get_current_api() == libremidi::API::DUMMY);
+    }
+  }
+
+  GIVEN("A midi input with a proper API")
+  {
+    libremidi::midi_in in(
+        libremidi::input_configuration{.on_message = [](auto) {}},
+        libremidi::kbd_input_configuration{});
+    THEN("created with the correct api")
+    {
+      REQUIRE(in.get_current_api() == libremidi::API::KEYBOARD);
+    }
+  }
+
+  GIVEN("A midi 2 input with a proper midi1 API")
+  {
+    libremidi::midi_in in(
+        libremidi::ump_input_configuration{.on_message = [](auto) {}},
+        libremidi::kbd_input_configuration{});
+    THEN("created with the correct api")
+    {
+      REQUIRE(in.get_current_api() == libremidi::API::KEYBOARD);
+    }
+  }
+}
+
 TEST_CASE("poly aftertouch", "[midi_in]")
 {
 #if __has_include(<jack/jack.h>)