API & App/Web Interface to manage USPlay

[cRaZy-bisCuiT]

Issue type: Feature request

Features

1. API to access & configure USPlay local network

   • provide an API to control USPlay

2. App/Web interface to Configure USPlay in runtime

   • Provide a way of configuring USPlay in runtime. We could either provide an App for mobile devices (Android, iOS, etc.) or a responsive (for different screen sizes like Notebook, Tablet, Smartphone) web interface which could be accessible in the local network.

Features Some ideas, what could be implemented/exposed on such a Interface:

• Queue -> play those songs after the current one is finished (a searchable library should be exposed to make that possible)
• change Player Name for the next songs in advance -> nice for toplists, so if the mics are rotaded the player name does not stay the same the whole evening for each microphone/colour
• adjust volume level
• activate / deactivate video playback
• TBA

[basisbit]

As far as I know Performous did implement a webapp to do some of those features in a local network. Might be a good start to get inspired by their API.

Anyways, you are mixing UltraStar Play and UltraStar Deluxe a bit there. Could you edit the issue description so that it is clear what you want to control?

[cRaZy-bisCuiT]

Sorry for that. Since we're at the USDP repo, Play is meant. Ofc having those features in USDX as well would be nice. I assume the future might be brithter for USDP. Maybe the same code base could be shared on both projects.

[basisbit]

*USP or USPlay or UltraStar Play

[achimmihca]

From #245, the idea came up that the API and thus Companion App should allow to

• add player profiles
• select songs, players, and their mic for the next round(s)
  • this corresponds to the "queue" feature as suggested above

Vocaluxe also has a similar "Smartphone control" feature.

[Baklap4]

Feel free to take a look over at our api from performous To be fair it has its problems and isn't the most beautiful api i've written. We have an open issue to refactor it.

Some other api's would be nice to consider:

• Stats How many songs How many songs played How many open connections // concurrent users Best scored songs ** Least scored songs

Imho i would scratch adjusting the volume as this could potentionaly have nasty side effects if not done with care (blowing up speakers).

• Admin api to change different runtime settings

• Songs Queue Info about a specific song ** Time till queue is done

• Players ** Mic configuration

[achimmihca]

The performous api has some redundant endpoints, e.g., GET "/api/getplaylistTimeout". The GET http method and get in URL is redundant.

As convention, I suggest to use GET http method for reading stuff, POST to create, PUT to update stuff, and DELETE to remove stuff.

Example (method, endpoint, json-body):

• GET /api/player
  • returns the list of player profiles
• GET /api/player/0
  • returns details to player profile with index 0
• POST, /api/player, {"name":"bob"}
  • create new player profile
• PUT /api/player/0, {"difficulty": "easy"}
  • update existing player profile with index 0.
• DELETE /api/player/0
  • delete existing player profile with index 0.

Instead of an index, an id can be used where possible. For songs, I would use their hash as id.

I think this a common approach. For another example, see the JIRA REST API

Further, I suggest to sent also available endpoints for an object to the client, not just the object's data itself. This way, the client does not need to know how the endpoints are formed (at least not all of them). Example: GET "/api/player" could return {"players": [{"name": "bob", "actions": {"getDetails": "api/player/0", "getImage": "api/player/0/image"}]}

I will create a wiki page with a REST API draft when I find time.

[achimmihca]

What should also be considered is some sort of whitelist for devices.

If you have 20 players and everyone can add songs and change player profiles, then chaos will be inevitable :) So, the main game should only allow some of its actions from whitelisted devices (specified as IP address).

[Baklap4]

The performous api has some redundant endpoints, e.g., GET "/api/getplaylistTimeout". The GET http method and get in URL is redundant.

You're correct there's currently an open issue trying to resolve that and thinking more into 'data endpoints' Your suggestion in regard of the player api is pretty much restful which is a good thing.

If you have 20 players and everyone can add songs and change player profiles, then chaos will be inevitable :) So, the main game should only allow some of its actions from whitelisted devices (specified as IP address).

Pretty easy fix for this would be to add basic authentication. Without it you can only read data, with it you can also post data

[achimmihca]

Pretty easy fix for this would be to add basic authentication.

Actually I would want to avoid anything security related such as passwords. Sure, its just a game but people might still use their PayPal password in such an insecure connection.

Also, if someone in the crowd guesses the password, then it's chaos again. Note that there is plenty of time to guess while others are singing. Using an IP whitelist just appears as a simpler solution to me with less potential for unlucky stuff.

Without it you can only read data, with it you can also post data

I like that part. Would also work with a whitelist.

[Baklap4]

Passwords vs IP's, as you're already in a local network (which could be password protected) guessing someones ip is actually more easy to do as for most routers they do just +1 after the last assigned ip, some trial and error and you have the host ip.

A random password on the other hand can be bruteforced.

The latter will be a bit more harder than guessing ip's.

To encounter someone using their own paypal password the server could generate a password upon every startup. This code will then only be known by the host which he can freely distribute to whoever he wants. Since it gets regenerated guessing it will get pretty hard.

Either way some kind of protection would be nice 👍

[achimmihca]

A random password on the other hand can be bruteforced.

Mmmh, there is already a UUID generated to identify a Companion App. I did this because my IP changed some times. So IP address whitelist is not a good idea after all.

So new idea:

• The NetworkOptions shows a list of connected clients.
• Each list entry has a checkbox to "grant write access".
• The list of device UUIDs with write access is stored as part of the normal game settings.

This way, no passwords are needed and the person in control of the main game is in control who else can change stuff. Nice UX and the client implementation does not even change because the UUID is already there. And yes, an attacker can still change everything if he knows a UUID with write access. So what 😝

[Baklap4]

The NetworkOptions shows a list of connected clients. Each list entry has a checkbox to "grant write access".

I like the idea of it being integrated into the software itself. However upon singing you can't add other people to the write access list without interrupting singing. Maybe that's something to think about on how to tackle that subject if it's even a usecase to begin with

if he knows a UUID

Goodluck with that hahah!

[basisbit]

Uh, PLEASE do not create a PR where you do IP address filtering or require users to enter a shared secret. Instead, please add a settings screen for device pairing, and while that screen is opened, clients can initiate connection to the UltraStar Play server, then the client and UltraStar Play show a few easily distinguishable unicode icons and require the user to check that they are the same, then the user confirms and those devices are paired. Then the next device can initiate pairing (or the next device from a waiting queue will be shown for pairing).

Would be nice to be able to have a button which allows for resetting the list of trusted devices.

This does not require users to enter any password or shared secret or similar, and also is really easy to use for small setups as well as bigger events.

However upon singing you can't add other people to the write access list without interrupting singing.

I'd definitely call this a feature, not a bug.