Protocol documentation

[pingdynasty]

Detailed documentation of the message types, structures and sequences would be invaluable to projects which can't use the library code directly.

[brunchboy]

I agree wholeheartedly. For example, there is not a current implementation for the Java VM ecosystem, and it is impractical to try to build and ship JNI binaries for every possible platform, so it would be delightful to be able to implement a pure Java compatible library.

I believe this may be a while in coming, though, as Ableton has spent a great deal of effort tuning the performance of their library for performance and correctness, and are concerned about issues arising from other people trying to interoperate with it.

That is inevitable, of course, and clear documentation would help us do it well, but it requires a change of mindset.

[brs-ableton]

Over time we would like to generate more detailed documentation about how the library works, but our goal with this will likely be geared towards general understanding rather than facilitating the development of alternate implementations. This is simply because, at this time, we strongly believe that it's in the best interest of users to have a standard implementation.

A misbehaving application in a Link session can ruin the session for everybody, and it may not be clear to any of the users what has gone wrong or which application is at fault. This is already a significant challenge with many applications using the same library. Adding multiple library implementations to the mix, each with their own idiosyncrasies, bugs and versions, would dramatically increase the likelihood of incompatibilities between supposedly Link-enabled applications. This would threaten the "it just works" user experience that is a major component of Link's appeal.

In any case, the code is ground truth and is a more precise formulation of the algorithms and protocols than any documentation we would reasonably be able to generate at this time. I don't mean to be dismissive in saying that - it's just that the effort required to generate a standards-like document that would allow independent development of an alternate implementation is way more than we can sign up for right now. In the absence of such a document, a deep understanding of the code would really be necessary for anyone attempting an alternate implementation.

[brunchboy]

Understood, and thank you so much for providing that code so we have the option! It is a vastly more friendly and useful starting point than the spanned switch ports and network captures we’ve had to rely on in order to be able to synchronize with Pioneer club gear, for example! 😀 In that world we are having to come up with our own standards-like documents through trial and error. But it is still working well enough that people are using it in giant stadium shows, sometimes even to synchronize with Live (even though that part can currently only be done via MIDI Clock and CC messages, and Link would be so much nicer).

Because of the fact that it would be impractical to the point of eccentricity to build, test, and bundle dozens of native libraries linked via JNI in order to bridge Link to the JVM on all the operating systems and architectures we might care about, when Link is essentially a network protocol, and the JVM world already has excellent, industrial-strength networking and threading support, if Ableton doesn’t pursue an official Java native implementation, that is likely where you will first face a third-party implementation. Perhaps even by me, depending on how much time I have for my free, open-source work, and what other things my community needs in the mean time. (And I should note that I’ve already had an issue opened asking when I would be able to support Link now that you have released this.)

But I would also be happy to collaborate with you on the Java implementation, and perhaps even on documentation that would facilitate other quality implementations, if there ever are people and hours available.

[abique]

Hi,

There are so many hosts which are not GPL and which would like to use Link. By setting the license to GPL, are you really pushing a standard library?

Regards, Alexandre

[nre-ableton]

@abique non-GPL hosts can request a license by emailing link-devs@ableton.com.

[abique]

@nre-ableton thank you! Mail sent, finger crossed.

[pingdynasty]

From my point of view, the shortcoming of the library is that it relies on things like STL and is unsuitable for use on embedded hardware (bare bones, not Linux). Considering the many embedded use cases for Link, I think this is unfortunate. As a case in point, I'd love to integrate Link into our Eurorack WiFi module, but it would require writing a new implementation from scratch. Without basic docs on message structures and state machine that is rather daunting. Granted, having access to good quality source code for the reference implementation makes this much easier than it otherwise would have been.

[brs-ableton]

@pingdynasty Yes, when developing Link we had to consider the tradeoff between our productivity in developing the library and which platforms to support. Standard C++11 was the choice and I think it's worked out pretty well for us so far, but as you say it presents a problem with some embedded applications. Do you mind sharing the architecture / tool chain you're using?

[pingdynasty]

@brs-ableton The product is called Open Sound Module and is an OSC to CV/Gate interface [1], and is open source [2]. It uses the Particle Photon hardware [3] and Broadcom / Cypress WICED libraries [4].

The architecture is ARM Cortex M3, bare bones, gcc toolchain: arm-none-eabi-gcc.

Standard C++11 is fine for us. It is STL, threads and exceptions in particular that are difficult for small footprints. Looking at the code, it seems difficult to remove those dependencies without a complete rewrite.

I still think you've done a great job to develop the library the way you have. Inevitably it won't suit every purpose, so alternative implementations will no doubt follow. A compliance test-suite built on the library would be amazing :-)

[1] http://www.rebeltech.org/products/open-sound-module/ [2] https://github.com/pingdynasty/OpenSoundModule [3] https://www.particle.io/ [4] http://www.cypress.com/internet-things-iot

[abique]

@nre-ableton Hi, I sent my request almost 2 weeks ago, but still no response. Maybe your system lost the mail in the way?

[nre-ableton]

@abique Hmm, that's not good. I'm not on that mailing list myself, but I will ask around and see what the status is.

[fgo-ableton]

@abique Thanks for sending the request. I confirmed it got here. There are apparently some delays on our side - should be sorted out soon.

[abique]

@fgo-ableton Hello, is there any update? Do you have any idea when we'll find out?

[joa77]

Hello @fgo-ableton is there any possibility to get a detailed protocol description?

[fgo-ableton]

@joa77 Sorry, but the state of this still has not changed.