Mixedreality-webrtc: Notes about the documentation

[drejx]

Hello,

As I've been working through getting the MixedReality SDK integrated into my project I took notes of areas in the documentation that caused some confusion for me and some things I think could be improved. I'm providing my notes to help out and hopefully make the onboarding process smoother. No worries if you decide not to take any suggestions, I won't be offended :) If you want any clarification on some points I'd be happy to do so as well.

---

https://github.com/microsoft/MixedReality-WebRTC
"Binary packages"

It states: "MixedReality-WebRTC is currently under development, and precompiled binary packages for the project's libraries are not yet available. See the Building MixedReality-WebRTC sections below for compiling those libraries from sources."

But binary packages are available on NuGet so that is a big plus! It would be useful to mention and list the available NuGet packages, because there are many potential users who don't want to build from source (thinking a lot of Unity users in this boat).

---

https://microsoft.github.io/MixedReality-WebRTC/manual/building.html#environment-and-tooling
"Enviornment and tooling" section

The 3rd bullet says that the solution uses VIsual Studio 2019 with the MSVC v142 build tools, but it actually requires the MSVC v141 build tools (coming from VS 2017). This issue provides more details: https://github.com/microsoft/MixedReality-WebRTC/issues/14.

If someone follows the current instructions to use the standard VS 2019 and v142 toolset they will end up with a build failure, which is a terrible start :) I suggest mentioning that VS 2017 (or 2019 with the v141 toolset option installed) is required, but full VS 2019 is coming later.

---

https://microsoft.github.io/MixedReality-WebRTC/manual/cs/helloworld-cs-mediatracks-uwp.html
"C# Tutorial (UWP) - Add Local Media Tracks" section

The instructions seem to reflect the API that is available in the master branch, but not yet available in the NuGet released packages. For example this class and its use as a return value for AddLocalVideoTrackAsync() is not available in the NuGet package:

LocalVideoTrack _localVideoTrack;
_localVideoTrack = await _peerConnection.AddLocalVideoTrackAsync();

Unfortunately this will cause confusion because those same UWP instructions tell the user to download the Microsoft.MixedReality.WebRTC.UWP NuGet package (here: https://microsoft.github.io/MixedReality-WebRTC/manual/cs/helloworld-cs-setup-uwp.html) - the user tries the code snippet above and will get a compile error.

Maybe UWP instructions should follow what is listed in the "C# Tutorial (Desktop)" section (https://microsoft.github.io/MixedReality-WebRTC/manual/cs/helloworld-cs-core3.html), which has instructions for the API in the NuGet packages. I believe the Unity tutorial also generally follows that.

---

https://microsoft.github.io/MixedReality-WebRTC/manual/download.html
"C++ library" section

There is an error where it states "The C++ packages contain the shared library Microsoft.MixedReality.WebRTC.Native.dll as well as its import library (.lib) and debug symbols database (*.pdb).". There are no .pdb files in the nuget package (the case in v1.02 at least)

---

https://microsoft.github.io/MixedReality-WebRTC/manual/installation.html
"Copying the C# library"

Would be useful to indicate the source location of the C# library within the unzipped nuget package hierarchy, i.e.

source (unzipped nuget) --> target (Unity Plugins folder)
lib\netstandard2.0\Microsoft.MixedReality.WebRTC.dll --> Assets\Plugins\Win32\x86_64

---

https://microsoft.github.io/MixedReality-WebRTC/manual/helloworld-unity-importwebrtc.html

Here it says you have to build the MixedReality C++ and C# DLLs from sources as they aren't provided as pre-built libraries. This isn't really true because you can get them from the nuget packages as outlined in the docs in an earlier section (https://microsoft.github.io/MixedReality-WebRTC/manual/installation.html). To make it more clear I suggest having 2 sections:

1) Extract the MixedReality C++ and C# DLLs from the nuget packages (no compiling required).
2) Build the MixedReality C++ and C# DLLs from source code.

---

https://microsoft.github.io/MixedReality-WebRTC/manual/building.html
Building from Sources

It would be really useful to include a note/table that indicates which DLLs you need to grab from where. I initially got a bit stuck because I copied the Microsoft.MixedReality.WebRTC.dll (.NET standard 2.0) to my project and made a reference to it, which compiled fine, but then I got a runtime exception while attempting to call a webrtc function. I realized I needed to include the Microsoft.MixedReality.WebRTC.Native.dll as well, which was the meat of the logic. I had to specifically include the DLL from the Microsoft.MixedReality.WebRTC.Native.UWP project as I have a UWP app. But when I tried to add the native DLL directly as a reference in my UWP project, I got this error dialog: "A reference to Microsoft.MixedReality.WebRTC.Native.dll could not be added. Please make sure tha the file is accessible, and that it is a valid assembly or COM component." By looking at the file structure of the Microsoft.MixedReality.WebRTC.TestAppUWP example I figured out I simply had to copy the native DLL into my app's deployment (AppX) folder.

I think a table just detailing what you need might be useful, for example:

Type |                   Source DLLs                                 |               Where to add to your project
---------------------------------------------------------------------------------------------------------------------------------
     | bin\netstandard2.0\Release\Microsoft.MixedReality.WebRTC.dll  | Include in "References" of your VS project
 UWP |---------------------------------------------------------------|-----------------------------------------------------------
     | bin\UWP\x64\Release]Microsoft.MixedReality.WebRTC.Native.dll  | Copy to target deployment folder (same as where .exe is)
---------------------------------------------------------------------------------------------------------------------------------
     |
C#   |  ...
     |
---------------------------------------------------------------------------------------------------------------------------------

The DLLs needed are not super obvious especially for those not used to interop between CSharp/C++ layers and any info to help them will make it as frictionless as possible.

---

NOTES FINISHED

I would to add that this is a great project and the documentation is already above par from what I've seen around. I'm hoping some of my suggestions make sense and help to improve the first-time experience :)

Cheers,
Andrej

[djee-ms]

Hi @drejx,

All very good points, many thanks for the detailed report!!
I will see to get those fixed. Some might take more time due to the fact we now have 2 branches (master with active development and breaking changes, and release/1.0 with stable NuGet release) but the documentation system has not been updated yet to handle multiple versions, which is the source of some of the mismatches like LocalVideoTrack. Nevertheless we need to fix those to avoid confusions.

Thanks again!

[djee-ms]

Note - The documentation now supports multiple branches, and documentation for release/1.0 and master being separated this should avoid confusion on features being supported or not. See the drop-down control at the top right of the page.

[djee-ms]

Updated the docs with all feedbacks still relevant, thanks!