1.0

Musicorum Scheme 1.0

This scheme is still a draft

The Musicorum Scheme 1.0 defines the request rules for a standard communication.

Table of contents

1. Workers
   1. Lookup
   2. Generate
2. Content Manager
3. Gateway
   1. Authorization
   2. Generate
   3. Workers
   4. Status

Workers

Lookup

The lookup connection corresponds as the first connection from the gateway to the worker nodes to define the availability of the nodes and their available themes.

For each node, the gateway must make the following request and response:

Note: workers are recommended to be local and not public to the world.

GET https://worker.musicorumapp.com/metadata

{
  "name": String, // Name of this particular worker
  "engine": String, // The generation engine used by this worker
  "version": Float, // The current version of the engine
  "scheme": Float, // The scheme version used
  "themes": String[] // An array of available themes
}

Example

Content-Type: application/json; charset=UTF-8

{
  "name": "rachel",
  "engine": "chloe",
  "version": 1.0,
  "scheme": 1.0,
  "themes": [
    "grid"
  ]
}

Response code: 200 (OK); Time: 16ms; Content length: 79 bytes

With the response, the gateway should map all the themes with their available workers.

Generate

This is the method that the `gateway` will use to generate the image. The gateway must send all the data, as `ThemeData`, used to render the image, like texts, images, and everything done, without the worker needing to make other requests. After the generation, the worker must save the image on the export path, shared with all the other services.

Note: Some themes does not require the user data, so it may return null for these cases. hide_username may also not be usable, but it's better to end false instead of null. Request

POST https://worker.musicorumapp.com/generate

{
  "id": String,
  "user": null | {
    "username": String,
    "name": String,
    "scrobbles": Integer,
    "image": String
  },
  "theme": String,
  "story": Boolean,
  "hide_username": Boolean,
  "data": ThemeData
}

Response:

{
  "file": String,
  "duration": Number
}

Example

POST https://worker.musicorumapp.com/generate
Content-Type: application/json; charset=UTF-8

{
  "id": "UMKp4hQJTVaEet2pWaHwUqGtBHKSogAyCdCvjqayTH94xj",
  "user": {
    "username": "metye",
    "name": "matheus",
    "scrobbles": 22193,
    "image": "https://i.scdn.co/image/ed0552e9746ed2bbf04ae4bcb5525700ca31522d""
  },
  "theme": "grid",
  "story": false,
  "hide_username": false,
  "data": {
    "tiles": [
      {
        "image": "https://i.scdn.co/image/ab67616d0000b2736040effba89b9b00a6f6743a",
        "name": "Replay",
        "secondary": "Lady Gaga"
      },
      {
        "image": "https://i.scdn.co/image/ab67616d0000b2733899712512f50a8d9e01e951",
        "name": "Play Date",
        "secondary": "Melanie Martinez"
      },
      ...
    ]
  }
}

>>>

{
  "file": "UMKp4hQJTVaEet2pWaHwUqGtBHKSogAyCdCvjqayTH94xj.webp",
  "duration": 2.586826895
}

Content Manager

This section represents the Content Manager, a micro service managed to cross-match and fetch infromation from external sources (such as Spotify or Deezer) using cache, in order to get data that Last.fm API does not provide or it would consume too many requests. This may be applicable for fetching artist images, audio features, or anything else.

This service is currently without documentation in order of future changes

Gateway

The gateway service is the proxy that redirects, queue, organize and controls all the other services. The service is also open to the public internet

Authorization

Every request made to the Gateway needs to be authenticated and must have this header:

Authorization: <API KEY>

Generate

This represents the endpoint responsible to handle the image generation. It needs a Last.fm user(represented by user), a valid theme(represented by theme), a story option, and the ThemeOptions(represented by options), which is relative to the choosen theme, defined here. There's also a hide_username boolean, that hides the username on the image if true.

Request:

POST https://generator.musicorumapp.com/generate

{
  "user": String,
  "theme" String,
  "story": Boolean,
  "options": ThemeOptions,
  "language": String,
  "hide_username": Boolean
}

Response:

If success:

{
  "success": true,
  "id": String,
  "worker": {
    "name": String,
    "engine": String,
    "version": Float,
    "scheme": Float,
  },
  "result": String
  "total_duration": Float,
  "generation_duration": Float
}

If error:

{
  "success": false,
  "error": String,
  "message": String
}

Example

If success:

Content-Type: application/json; charset=UTF-8

{
  "success": true,
  "id": "gOOLkrHAROqPUgDCCBUPq-AWRnN1cBw5Y0v3qriQ29Rf0w",
  "worker": {
    "name": "rachel",
    "engine": "chloe",
    "version": 1.0,
    "scheme": 1.0,
  },
  "result": "https://result.musicorumapp.com/gOOLkrHAROqPUgDCCBUPq-AWRnN1cBw5Y0v3qriQ29Rf0w.webp",
  "total_duration": 2.98003462,
  "generation_duration": 2.472550765
}

Response code: 200 (OK); Time: 1936ms; Content length: 748 bytes

If error:

Content-Type: application/json; charset=UTF-8

{
  "success": false,
  "error": "USER_NOT_FOUND",
  "message": "Last.fm user not found."
}

Response code: 404 (NOT FOUND); Time: 457ms; Content length: 356 bytes

Workers

WIP

Status

WIP