Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

QML mapping requirements #6

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

QML mapping requirements #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions proposals/2024-07-15_qml_mapping_requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
## QML mapping requirements

* **Owners:**
* Daniel Schürmann

* **Implementation Status:** `Not implemented`

* **Related Issues and PRs:**
* Create a reactive programming API for controllers [#13440](https://github.com/mixxxdj/mixxx/issues/13440)
* QML-based components API for controllers [#13459](https://github.com/mixxxdj/mixxx/pull/13459)
* Respect the Midi timestamp when scratching [#6951](https://github.com/mixxxdj/mixxx/issues/6951)
* make brake, soft start, and spinback part of the effects system [#8867](https://github.com/mixxxdj/mixxx/issues/8867)

* **Other docs or links:**
* `<Links…>`

* ** This document shall collect requirements and expectation a new mapping system based on QMl shall fullfill and shall not fulfill.

## Why

It’s important to clearly explain the reasons behind certain design decisions in order to have a consensus
between team members, as well as external stakeholders.

It turned out that we have conflicting or unclear requirements. We need to decide the way forward to not end up with a blocked PR or double work.
We need to decide which of them are mandatory optional.

### Pitfalls of the current solution

TODO

## Goals

Here is a fist draft of requirements

1. User Requirements

1.1 Good performance, responsive scratching (Real-Time)
1.2 Easy reassign buttons and sliders
1.3 Easy map a new controller from the scratch

2. Mapping Developer

2.1 Everything at one place, one file, folder, pack
2.2 Easy to share
2.3 Reuse common programming skills
2.4 High abstraction level
2.5 Complete API documentation
2.6 Good IDE support .. code completion.
2.7 On the fly edits, no Mixxx restart.
2.8 Stable: Compatible to future Mixxx versions

Comment on lines +35 to +51
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. User Requirements

1.1 Good performance, responsive scratching (Real-Time)

I believe this can be achieved, however scratching is IMO orthogonal to QML. The missing piece here is the ability to take message timestamps into account, which has nothing to do with QML perse and is mostly an API extension in general.

1.2 Easy reassign buttons and sliders

I think this depends on the definition of easy. If the mapping is written in a Components-oriented fashion, it won't be just simple point-and-click, but we can still retain the C++ dispatcher code that is point-and-click friendly.

1.3 Easy map a new controller from the scratch

This also hinges on the definition of easy. Knowing QML and MIDI fairly well, I'd say its easy. For someone that has never opened a text editor with code, not so much.

2.1 Everything at one place, one file, folder, pack
2.2 Easy to share

That should be fairly achievable for QML, however it does require a little bit of automated work to make the mapping "export-ready". So the current plain copying files wouldn't work and instead we'd need an export button that prepares the mapping accordingly. That prepwork would primarily consist of ensuring the built-in shared modules are bundled correctly.

2.3 Reuse common programming skills
2.4 High abstraction level
2.5 Complete API documentation
2.6 Good IDE support .. code completion.
2.7 On the fly edits, no Mixxx restart.
2.8 Stable: Compatible to future Mixxx versions

Should all be possible, especially when we can take advantage of QMLs built-in API versioning mechanics. IDE support hinges a little bit on the maturity of the qml-language-server.

## Non-Goals

TODO

## How

### Ideas for discussion

> we can't make the metadata parsing independent from a QMLEngine

That is correct if we use only one parser. I can image to workaround that by a stripped Mixxx QML parser. reading a file hash, is in this context the minimum version of such parser, but we can read also other info.

> We would need to serialize it into a separate file in a format that we can actually manipulate.

I can imagine QT does exactly that. Maybe we can copy from them and use it for our second parseing.

The other topic is how the data stream is handled. I like to keep the connection factory and the dispatcher in the C++ domain, controlled by QML XML or JS to share concepts between the mapping types. I can also imagine to read the mapping by XML and write them as QML or such for an easy transition.

Another point that bugs me is the weak scratching stability and the programming skills required to map the jogg wheel. Both can be targeted by handling the jog in wheel in the C++ domain and configure it from QML XML or JS.

## Alternatives

The section stating potential alternatives. Highlight the objections reader should have towards your proposal as they
read it. Tell them why you still think you should take this path.

1. This is why not solution Z...

## Action Plan

The tasks to do in order to migrate to the new idea.

* [ ] Task one <GH issue>
* [ ] Task two <GH issue> ...
Loading