Introduction

Protocol

Karaoke Mugen App uses a Socket.IO ver. 3 connection to handle all API requests, it also carries events about currently playing song and playlist or users updates.

The same protocol is used by Karaoke Mugen Server to provide remote control and shortener.

Each request has its associated event and is acked by the server whenever the request is fulfilled.

socket.emit('CommandName', {...}, res => {})

Anatomy of a request

Each request is populated with, if needed, credentials and a payload (body).

{
    // Request payload, can be of any type
    body: {}
    // JWT token (local authorization, obtained by using login endpoint)
    authorization: ''
    // JWT Token (remote authorization, KMServer)
    onlineAuthorization: ''
}

Anatomy of a response

Each answer is formatted like this { err: boolean, data?: any }. If err is true, most of the time, the error will be formatted with a numeric code (similar to what HTTP err codes can mean) and a message.

{
    err: false,
    data: {
        // ...
    }
}

{
    err: true,
    data: {
        code: 404,
        message: {
            code: 'UNKNOWN_COMMAND'
        }
    }
}

{
    err: true,
    data: {
        code: 503,
        message: {
            code: 'WEBAPPMODE_CLOSED_API_MESSAGE'
        }
    }
}

{
    err: true,
    data: {
        code: 403,
        message: {
            code: 'ADMIN_PLEASE'
        }
    }
}

{
    err: true,
    data: {
        code: 403,
        message: {
            code: 'NO_GUEST'
        }
    }
}

Requests and response format

Requests of all endpoints will be described as contents of the body object.

Responses from all endpoints will be in the data object for the response.

Example

import { io } from 'socket.io-client';

const socket = io();

socket.emit('login', {
    body: { username: 'hello', password: 'W0rld!!!' }
}, res => {
    console.log(res);
    /*
        {
            err: false,
            data: {
                token: '',
                // ...
            }
        }
    */
});

REST API access

This allows you to send an API command through a REST endpoint, if you don't want to use websockets.

{
    cmd: 'getKaras',
    body: {
        body: {
            filter: 'Dragon Ball Z'
        },
    },
    authorization: 'abcdefghijkl...'
}

See getKara response in API documentation.

{
    ...
}

Uploading files

Uploading files is not done through the Websocket API as it tends to overload the protocool with big files, so we use instead a REST endpoint for that.

{
    file: <data>
}

{
    originalname: 'avatar.png' // Name on the user's computer,
    filename: 'abcdefghijklmn' // Name on the server
}