The Future (version 1.0)

[jesperstarkar]

This thread should be where we discuss and work together to shape the future branch. I suggest we link inn commits/branches and standalone Gists here to try ut and discuss structures an concepts. I will start off by listing my ideas and motivations behind introducing braking changes and change the future.

Project

• ~~casparcg-connection will not go into 1.0 before the Future is merged to Master.~~
• Future will not be merged unless it has documentation and examples in the Wiki.
• ~~Future will have breaking changes, and this is OK, since the current Master not is widely spread, and not considered stable yet.~~

Two-layer structure

• The top priority is to split casparcg-connection into two layers.
• The top-level casparcg()-object of today will be renamed casparcg-amcp-connection(). The new casparcg-amcp-connection() will be a dumb layer only concerning socket connection and the AMCP protocol.
• A new casparcg() object will be the top-layer, using amcp-connection() but with smart logics and convenience applied.
• The main design goal is to not make any decisions on behalf of the user in the casparcg-connection(), like i.e. automatic querying of current server version etc.
• casparcg() could have a separate casparcg-osc-connection() added later on.

Namespaces

• I have yet to find out how to best implement multiple versions of the AMCP protocol. I'm not sure this is best done wit namespaces. This is one of the major concerns for the new structure.

Commands

• I want to remove the idea of parsing strings into high-level command-objects at a command-level. Such a parsing could be added to casparcg(), but at the moment I don't see the point of this idea at all. It was a main premise for the first version of this library, but have never been used nor maintained. It should just go away, to open up for better concepts such as:
• The promise of a command should live within the command (the command should be a promise?), not being created by the queue in casparcg()? If not, it should at least be possible to create promises from commands without adding them to the queue.
• All parameters of an AMCP command should be native properties of that object. Perhaps we need some Proxy object here? This would help documentation a lot, especially when we split out the command objects from the top-level.

[jesperstarkar]

@realies, I am thinking of starting the Future separation over the next few days. The most crucial decisions to make from the start is how to handle separation between 2.0 and 2.1. I'm not sure if namespaces are the right way to go.

Ideas?

[mint-dewit]

The casparcg()-object could perhaps implement a websocket-connection()-object as well that would connect with a websocket server that proxies low level amcp-commands. That way we'd have the same API in the browser (inside html templates) that we'll have in node js.

[jesperstarkar]

Brilliant idea.

[mint-dewit]

Considering parsing:

An object / class that has two methods: toAmcp(commandObject) and fromAmcp(string) Then either pass the amcp version as an argument, or use a globally defined version. At a lower level the parsers for 2.0 and 2.1 can have a different code base completely.

[realies]

@jesperstarkar, looking at the documentation, namespaces is the way to go for internal modules. After spending some time reading the library source code it seems v2.1 commands derive from v2.0 commands. From my usage and brief comparison of both AMCP protocols it seems that newer version commands can have argument type changes (e.g. LOADBG v2.0 vs v2.1), extended functionality by having more arguments (e.g. SWAP v2.0 vs v2.1) or completely new commands.

Perhaps extending an old AMCP protocol with its next version and overriding or adding methods that differ could be a way to go for future iterations?

The idea of exposing a websocket protocol that allows for clients to talk AMCP with the server and be able to subscribe for OSC state changes would make the library a great tool for low latency web-based applications.

[jesperstarkar]

Yup. Then we need to extend all classes/methods into the 2.1 namespace, so that the reference will have a complete set, even if 90% only inherits Super directly.

I'm thinking of archiving everything in the future branch under a tmp folder, then starting building ground up, sketching out the interfaces before copying over implementations.

[jesperstarkar]

@baltedewit pointed out that he wanted to see the docs/ gone from the repo. I still like the idea with the docs being in sync with the code, and the docs page being driven by the repo. Ideas?

[realies]

Makes sense if docs (API) are generated from each commit. Although a user might benefit if there is more examples or suggested usage and a fuller description of library classes and methods. Typedoc exports comments as descriptions in the docs, but is that a suitable place for more?

[super-ienien]

hi,

For the future, I think optionnal arguments of AMCP commands should be a single Javascript Object like this : play(1, 1, {clip: 'AMB', seek: 25})

[realies]

@super-ienien, are you suggesting optional parameters to be inserted as an object?

[super-ienien]

Yeah sorry if my message wasn't clear. Yes I am suggesting inserting optionnal parameters as properties of a single object. It is easier to deal with an object than with an ordered list of parameters. It permits to skip parameters that have a default value and to only pass parameters that we wan't

[jesperstarkar]

@super-ienien Absolutely! I will drop the initial attempt of parsing commands strings. And we should accept a value object as you suggest, AND I want to have native properties of the command-object itself!

var foo = new PlayCommand({channel: 2}); foo.channel = 1;

[jesperstarkar]

casparcg-connection will not go into 1.0 before the Future is merged to Master.

Wrong: Using StandardVersion, versions will from now be decide from the nature of changes. All breaking changes bumps the major part.

Future will have breaking changes, and this is OK, since the current Master not is widely spread, and not considered stable yet.

But: Breaking changes will also happen om master before the future.

[jesperstarkar]

The promise of a command should live within the command (the command should be a promise?), not being created by the queue in casparcg()? If not, it should at least be possible to create promises from commands without adding them to the queue.

v3.0.0 leading up to this: From 3.0.0 there will be more steps involved in creating and queueing commands. This is preparation for more flexible ways of handling commands and queues. The new public API includes: