Merge pull request #252 from microsoft/pete-dev

Initial documentation refactor

README.md

@@ -10,19 +10,6 @@ Here's a high-level view of the end goal of this project. Details subject to cha
 
 ![High-level view of the MIDI stack](img/high-level-view.png)
 
-## Key Features
-
-* **Multi-client by default**. Unless an endpoint is configured to not allow shared connections, or there is some issue around multi-client in a third-party driver, any endpoint (including MIDI 1.0 devices) can be used by multiple applications at the same time. So far, in our testing, we haven't found any USB devices or drivers which cannot be multi-client.
-* **Faster**. In our testing, we've found that the new infrastructure is much faster at sending and receiving messages compared to the older API, even with plugins configured in the service. There are no built-in speed caps or throttling in Windows MIDI Services, even for older USB MIDI 1.0 devices. The driver is not limited USB full-speed, and supports USB 3.x speeds.
-* **Lower Jitter**. Along with higher speed comes lower jitter. This will vary by transport type (USB vs Network vs Virtual), and the device Windows is talking to, but the jitter is in the low microsecond range even without any compensation.
-* **More Deterministic**. Speaking of latency compensation, the new API enables timestamp-based message scheduling for outbound messages, and also will soon support Jitter Reduction timestamps for MIDI 2.0 devices which can use them.
-* **Extensible**. The service has been designed to be extensible by Microsoft and third-parties. New types of transports can be added at any time, including during prototyping of a new transport specification. (We're working on Network MIDI 2.0, Bluetooth MIDI 1.0 and considering RTP, all using this model.) Similarly, message processing plugins can also be developed by Microsoft or third-parties and used for production and/or prototyping. **No kernel driver experience required in most cases.**
-* **App-to-App and Virtual MIDI**. Windows MIDI Services includes virtual / app-to-app MIDI 2.0 to enable lightning fast communication between apps on the PC. We're also investigating flexible routing between any MIDI endpoints as a future feature.
-* **Better tools**. We supply the `midi.exe` Windows MIDI Services Console for developers and power users, or anyone comfortable with the command line. You can use it to monitor endpoints, send and receive messages, send/capture SysEx data and much more. We'll deliver the MIDI Settings GUI app after our initial release. That app enables renaming devices, configuring your MIDI setup, testing, and more.
-* **UMP-Centric**. The new API fully embraces MIDI 2.0 and the Universal MIDI Packet format and handles all required translation in the service and driver. This makes the app model simple while ensuring all your existing devices continue to work.
-* **Open Source**. The source code is open and available to everyone under a permissive license. Not sure how something works? Want to create a transport but aren't sure how we did it? Want to investigate a bug or contribute a feature? The code is there for you to explore.
-
-Note: Additionally MIDI CI functionality, which does not technically require OS support, will be coming after version 1.0. We intend to add helpers for profiles, property exchange, MUID tracking, and more. In the meantime, applications can send and receive MIDI CI messages without anything in their way, using custom code or third-party libraries. MIDI CI is just MIDI 1.0-compatible SysEx.
 
 ## Key documentation
 

build/staging/version/BundleInfo.wxi

@@ -1,4 +1,4 @@
 <Include>
   <?define SetupVersionName="Developer Preview 5" ?>
-  <?define SetupVersionNumber="1.0.24035.2111" ?>
+  <?define SetupVersionNumber="1.0.24036.0045" ?>
 </Include>

docs/README.md

@@ -1,4 +1,38 @@
 # Microsoft Windows MIDI Services
 
+
+## Key Features
+
+* **Multi-client by default**. Unless an endpoint is configured to not allow shared connections, or there is some issue around multi-client in a third-party driver, any endpoint (including MIDI 1.0 devices) can be used by multiple applications at the same time. So far, in our testing, we haven't found any USB devices or drivers which cannot be multi-client.
+* **Faster**. In our testing, we've found that the new infrastructure is much faster at sending and receiving messages compared to the older API, even with plugins configured in the service. There are no built-in speed caps or throttling in Windows MIDI Services, even for older USB MIDI 1.0 devices. The driver is not limited USB full-speed, and supports USB 3.x speeds.
+* **Lower Jitter**. Along with higher speed comes lower jitter. This will vary by transport type (USB vs Network vs Virtual), and the device Windows is talking to, but the jitter is in the low microsecond range even without any compensation.
+* **More Deterministic**. Speaking of latency compensation, the new API enables timestamp-based message scheduling for outbound messages, and also will soon support Jitter Reduction timestamps for MIDI 2.0 devices which can use them.
+* **Extensible**. The service has been designed to be extensible by Microsoft and third-parties. New types of transports can be added at any time, including during prototyping of a new transport specification. (We're working on Network MIDI 2.0, Bluetooth MIDI 1.0 and considering RTP, all using this model.) Similarly, message processing plugins can also be developed by Microsoft or third-parties and used for production and/or prototyping. **No kernel driver experience required in most cases.**
+* **App-to-App and Virtual MIDI**. Windows MIDI Services includes virtual / app-to-app MIDI 2.0 to enable lightning fast communication between apps on the PC. We're also investigating flexible routing between any MIDI endpoints as a future feature.
+* **Better tools**. We supply the `midi.exe` Windows MIDI Services Console for developers and power users, or anyone comfortable with the command line. You can use it to monitor endpoints, send and receive messages, send/capture SysEx data and much more. We'll deliver the MIDI Settings GUI app after our initial release. That app enables renaming devices, configuring your MIDI setup, testing, and more.
+* **UMP-Centric**. The new API fully embraces MIDI 2.0 and the Universal MIDI Packet format and handles all required translation in the service and driver. This makes the app model simple while ensuring all your existing devices continue to work.
+* **Open Source**. The source code is open and available to everyone under a permissive license. Not sure how something works? Want to create a transport but aren't sure how we did it? Want to investigate a bug or contribute a feature? The code is there for you to explore.
+
+Note: Additionally MIDI CI functionality, which does not technically require OS support, will be coming after version 1.0. We intend to add helpers for profiles, property exchange, MUID tracking, and more. In the meantime, applications can send and receive MIDI CI messages without anything in their way, using custom code or third-party libraries. MIDI CI is just MIDI 1.0-compatible SysEx.
+
+## Resources
+
+### Main Sites
+
 * [Source Repo on GitHub](https://aka.ms/midirepo)
 * [Discord Server](https://aka.ms/mididiscord)
+
+### Developer Materials
+
+* [Get started examples](https://github.com/microsoft/MIDI/blob/main/get-started/README.md)
+* [API Documentation](developer-docs/client-api/)
+* [Samples](../samples/)
+* [Programming Languages FAQ](developer-docs/faq-programming-languages.md)
+
+### Windows MIDI Services Console app
+
+* [Console overview](midi-console.md)
+
+### Advanced Materials
+
+* [JSON Configuration File](config-json.md)

docs/_config.yml

@@ -0,0 +1,7 @@
+remote_theme: pages-themes/[email protected]
+plugins:
+- jekyll-remote-theme
+
+title: Windows MIDI Services Documentation
+description: User and developer documentation for the Windows MIDI Services project
+#show_downloads: true

get-started/midi-developers/app-developers/docs/README.md → docs/developer-docs/client-api/README.md

@@ -1,6 +1,5 @@
 # Documentation
 
-API and other documentation which will eventually be used in the Microsoft Learn docs portal. 
 
 | Page | Description |
 | ------------- | --------------------- |

docs/developer-docs/client-api/Windows.Devices.Midi2/README.md

@@ -0,0 +1,4 @@
+# Windows.Devices.Midi2
+
+API Types and information will show up here. For now, please refer to sample apps and other documents
+

get-started/midi-developers/app-developers/samples/csharp-net/app-to-app-midi-cs/MidiSample.AppToAppMidi/MainWindow.xaml.cs → samples/csharp-net/app-to-app-midi-cs/MidiSample.AppToAppMidi/MainWindow.xaml.cs

@@ -59,7 +59,6 @@ private void MainWindow_Closed(object sender, WindowEventArgs args)
             _session.Dispose();
         }
 
-        //const string _appDeviceConnectionId = "\\\\?\\SWD#MIDISRV#MIDIU_VIRTDEV_PMB_APP2_8675309#{e7cce071-3c03-423f-88d3-f1045d02552b}";
         private void OpenConnection()
         {
             try
@@ -85,16 +84,31 @@ private void OpenConnection()
                     MidiCIMessageVersionFormat = 0
                 });
 
+                deviceDefinition.FunctionBlocks.Add(new midi2.MidiFunctionBlock()
+                {
+                    Number = 1,
+                    IsActive = true,
+                    Name = "A Function Block",
+                    UIHint = midi2.MidiFunctionBlockUIHint.Sender,
+                    FirstGroupIndex = 1,
+                    GroupCount = 1,
+                    Direction = midi2.MidiFunctionBlockDirection.Bidirectional,
+                    Midi10Connection = midi2.MidiFunctionBlockMidi10.Not10,
+                    MaxSystemExclusive8Streams = 0,
+                    MidiCIMessageVersionFormat = 0
+                });
+
                 deviceDefinition.AreFunctionBlocksStatic = true;
                 deviceDefinition.EndpointName = "Pad Controller App";
-                deviceDefinition.EndpointProductInstanceId = "PMB_APP2_8675309";    // this needs to match pre-configuration for now
+                deviceDefinition.EndpointProductInstanceId = "PMB_APP2_3263827";
                 deviceDefinition.SupportsMidi2ProtocolMessages = true;
                 deviceDefinition.SupportsMidi1ProtocolMessages = true;
                 deviceDefinition.SupportsReceivingJRTimestamps = false;
                 deviceDefinition.SupportsSendingJRTimestamps = false;
 
+
                 System.Diagnostics.Debug.WriteLine("Creating session");
-                _session = midi2.MidiSession.CreateSession("App to app MIDI sample");
+                _session = midi2.MidiSession.CreateSession(deviceDefinition.EndpointName);
 
                 if (_session != null)
                 {
@@ -107,18 +121,21 @@ private void OpenConnection()
 
                         _connection.MessageReceived += _connection_MessageReceived;
 
+                        // do anything else needed here. The public endpoint is not available to other
+                        // applications until you open the device endpoint
+
                         System.Diagnostics.Debug.WriteLine("Connection created. About to open it.");
 
                         if (_connection.Open())
                         {
                             System.Diagnostics.Debug.WriteLine("Connection Opened");
 
-                            this.AppWindow.Title = "App-to-app MIDI Pad Controller: Connected";
+                            this.AppWindow.Title = deviceDefinition.EndpointName + ": Connected";
                         }
                         else
                         {
                             System.Diagnostics.Debug.WriteLine("Connection Open Failed");
-                            this.AppWindow.Title = "App-to-app MIDI Pad Controller: (no connection)";
+                            this.AppWindow.Title = deviceDefinition.EndpointName + ": (no connection)";
                         }
                     }
                     else
@@ -129,13 +146,11 @@ private void OpenConnection()
                 else
                 {
                     System.Diagnostics.Debug.WriteLine("Session Open Failed");
-                    // unable to open session
                 }
             }
             catch (Exception ex)
             {
                 System.Diagnostics.Debug.WriteLine("Exception: " + ex.ToString());
-
             }
         }
 

get-started/midi-developers/app-developers/samples/csharp-net/app-to-app-midi-cs/MidiSample.AppToAppMidi/MidiSample.AppToAppMidi.csproj → samples/csharp-net/app-to-app-midi-cs/MidiSample.AppToAppMidi/MidiSample.AppToAppMidi.csproj

@@ -29,7 +29,7 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.5.231202003-experimental1" />
     <PackageReference Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.26031-preview" />
-    <PackageReference Include="Windows.Devices.Midi2" Version="1.0.0-preview.3-0137" />
+    <PackageReference Include="Windows.Devices.Midi2" Version="1.0.0-preview.3-0139" />
     <PackageReference Include="WinUIEx" Version="2.3.3" />
     <Manifest Include="$(ApplicationManifest)" />
   </ItemGroup>