Playlists

Get list of playlists

getPlaylists Authentication needed Frontend needs to be restricted or open

Query list of playlists.

Guests or users will not see invisible playlists.

Response
[
    {
        plaid: 1,
        name: 'My Playlist',
        karacount: 49,                  // number of songs in playlist
        duration: 3600,                 // duration in seconds
        time_left: 1200,                // time left before playlist ends (based on song with flag_playing's position,
        created_at: '2021-01-02 13:30'  // Date object
        modified_at: '2021-01-02 13:30' // Date object
        flag_visible: true,
        flag_current: true,
        flag_public: true,
        plcontent_id_playing: 12        // Playlist content which has the flag_playing
        username: 'Axel'                // Who created the playlist
    },
    ...
]
Response
{
    code: 500,
    message: {
        code: 'PL_LIST_ERROR'
    }
}

Create playlist

createPlaylist Operator user required Frontend can be closed, restricted or open

Create a new playlist

Request
{
    name: 'My new playlist',
    flag_visible: true,
    flag_current: false,
    flag_public: false,
    flag_smart: false,
    flag_whitelist: false,
    flag_blacklist: false
}
Response
{
    plaid: 2
}
Response
{
    code: 500,
    message: {
        code: 'PL_CREATE_ERROR'
    }
}

Get single playlist

getPlaylist Authentication needed Frontend needs to be restricted or open

Get a single playlist

Request
{
    plaid: 2
}

See getPlaylists's response. You receive a single object instead of an array.
Response
{
    code: 500,
    message: {
        code: 'PL_VIEW_ERROR'
    }
}
Response
{
    code: 404,
    message: {
        code: 'PL_VIEW_ERROR'
    }
}

Edit playlist

editPlaylist Operator user required Frontend can be closed, restricted or open

Edit playlist's information

Request
{
    plaid: 2,
    name: 'My new renamed playlist',
    flag_visible: true,
    flag_current: true,
    flag_smart: true,
    smart_limit_order: 'newest', // or 'oldest'
    smart_limit_number: 100,
    smart_limit_type: 'songs', // or 'duration'
    flag_smartlimit: true,
    type_smart: 'UNION' // Or 'INTERSECT' for AND playlists
}

Only plaid is mandatory. Any omitted setting isn't modified.

Note on flag_public and flag_current : Setting these to false has no effect. You need to set another playlist as public or current first, as there can be only one playlist with these flags.

Simply returns.
Response
{
    code: 500,
    message: {
        code: 'PL_UPDATE_ERROR'
    }
}
Response
{
    code: 404,
    message: {
        code: 'PL_UPDATE_ERROR'     
    }
}

Delete playlist

deletePlaylist Operator user required Frontend can be closed, restricted or open

Delete a playlist and its contents.

Request
{
  plaid: 2
}

Simply resolves.
Response
{
    code: 500,
    message: {
        code: 'PL_DELETE_ERROR'
    }
}
Response
{
    code: 404,
    message: {
        code: 'PL_DELETE_ERROR'
    }
}

Usually happens if playlist is either current or public.

Response
{
    code: 409,
    message: {
        code: 'PL_DELETE_ERROR',
        msg: 'Playlist 1 is current. Unable to delete it. Make another playlist current first.'
    }
}

Empty playlist

emptyPlaylist Operator user required Frontend can be closed, restricted or open

Empty a playlist of all its songs

Request
{
  plaid: 2
}

Simply resolves.
Response
{
    code: 500,
    message: {
        code: 'PL_EMPTY_ERROR'
    }
}

Find playing song's index

findPlayingSongInPlaylist Operator user required Frontend can be closed, restricted or open

Find the currently playing song's index in a playlist. This helps when you do not load the full playlist and need to find out where the current song is to jump to it.

Request
{
  plaid: 2
}
Response
{
    index: 203
}

Note: index is -1 if flag_playing isn't set on any song in the playlist.
Response
{
    code: 500    
}

Get playlist contents

getPlaylistContents Authentication needed Frontend needs to be restricted or open

Returns an array of playlist contents.

Request
{
  plaid: 2,
  filter: null,
  from: 0,            // -1 if you want to get to the currently playing song's position
  size: 200,
  random: null        // Return X random songs from the playlist
  orderByLikes: false // Order results by number of likes/accepted/refused status
}

orderByLikes is useful for the suggestion playlist. It returns non-accepted/non-refused songs first, then accepted ones, then refused ones. It orders each group by likes in descending order.

Extends the Get Songs response with additional data :

Response
{
    infos: <see Get songs>
    contents: [
        {
            <see Get Songs>,
            criterias: [
                {
                    type: 7
                    value: <TID>
                }
            ], // Criterias list criterias used to get this song in the smart playlist (if we're listing a smart playlist's contents)
            created_at: <Date object>, // When the song was added to the playlist
            nickname: 'Axel-kun'       // Different from username, this is the nickname used when the song was added
            username: 'axel@kara.moe',
            avatar_file: 'abcdefgh.png',
            user_type: 'admin',
            pos: 4,                    // Position in playlist,
            playlistcontent_id: 39,
            flag_playing: true,        // Song is currently playing
            upvotes: 0,                // Number of upvotes,
            flag_visible: true,        // Song is visible in playlist to regular users/guests,
            flag_free: true,           // Song has been freed and doesn't count in a user's quota
            flag_refused: false,       // Song hasn't been refused by the operator yet
            flag_accepted: false,      // Song hasn't been accepted by the operator yet        
        },
        ...
    ]
}
Response
{
    code: 500,
    message: {
        code: 'PL_VIEW_SONGS_ERROR'
    }
}
Response
{
    code: 404,
    message: {
        code: 'PL_VIEW_SONGS_ERROR'
    }
}

Get playlist contents (micro)

getPlaylistContentsMicro Authentication needed Frontend needs to be restricted or open

This version only returns a small subset of information from a playlist.

Request
{
  plaid: '<uuid>',
}
Response
[
    {
        kid: <uuid>,
        username: axel@kara.moe, // Requester
        plcid: 20938,
        flag_playing: false,
        pos: 5,
        plaid: <uuid>,
        nickname: 'Axel Terizaki',
        flag_free: false,
        flag_visible: true, 
        flag_accepted: false,
        flag_refused: false,
        mediafile: 'FRE - Mahoromatic - AMV - Derniere Danse.mp4',
        repository: 'kara.moe',
        mediasize: 12319290,
        duration: 240
    }, ...
]
Response
{
    code: 500,
    message: {
        code: 'PL_VIEW_SONG_ERROR'
    }
}

Add song to playlist

addKaraToPlaylist Authentication needed Frontend needs to be open

Add one or several songs to a playlist at a given position.

Some checks are disabled when an admin uses this function.

Request
{
  plaid: '<uuid>',
  requester: 'Axel Terizaki' // Optional
  kids: [         // KIDs go here
    'bbbbbbbbb',
    'aaaaaaaaa',   
  ]
  pos: 2          // Optional, see below.
}

pos is optional.

  • If undefined, songs are added at the end of the playlist.
  • If specified, songs are added at pos.
  • If pos is set to -1, songs are added after the currently playing song.
Response
{
    plc: ...
}

plc contains the first song added's full Playlist content information. See response for more details. You can use notably plc.time_before_play to have an idea of when the sogn you added is going to play.
Response
{
    code: 500,
    message: {
        code: 'PL_ADD_SONG_ERROR'
    }
}
Response
{
    code: 400,
    message: {
        // Validation errors here
    }
}

Randomize a PLC

randomizePLC Operator user required Frontend can be closed, restricted or open

Randomizes one or more songs in a playlist

Request
{
  plc_ids: [239, 240, 289]
}

Simply resolves.
Response
{
    code: 500    
}

Copy song to another playlist

copyKaraToPlaylist Operator user required Frontend can be closed, restricted or open

Copies a song from one playlist to another.

Request
{
  plaid: 5, // Destination playlist
  plc_ids: [ // Source PLCs to copy
    53,
    13,
    22
  ]
  pos: 2
}

See how pos is treated in addKaraToPlaylist above

Simply resolves.
Response
{
    code: 500,
    message: {
        code: 'PL_SONG_COPY_ERROR'
    }
}
Response
{
    code: 400,
    message: {
        // Validation error here
    }
}

Remove song from playlist

deleteKaraFromPlaylist Operator user required Frontend can be closed, restricted or open

Removes a song from a playlist

Request
{
  plc_ids: [ 
    53,
    13,
    22
  ]  
}

Simply resolves.
Response
{
    code: 500,
    message: {
        code: 'PL_SONG_DELETE_ERROR'
    }
}
Response
{
    code: 400,
    message: {
        // Validation error here
    }
}

Get single playlist content

getPLC Authentication needed Frontend needs to be restricted or open

Retrieves a single song from a playlist. This contains additional information than the [get playlist contents](#get-playlist-contents) command.

Request
{
  plc_id: 12
}

Extends the response from the get playlist contents command.

Response
{
    <See get playlist contents>
    kara_created_at: <Date>,  // When the song was added to the repository
    kara_modified_at: <Date>, // When the song was last updated in the repository
    time_before_play: 134     // seconds before the song is due to play.
}
Response
{
    code: 500,
    message: {
        code: 'PL_VIEW_CONTENT_ERROR'
    }
}

Edit playlist content

editPLC Operator user required Frontend can be closed, restricted or open

Edit various information about a song in a playlist

You can specify only the items you want to change

Request
{
  plc_ids: [
      12,
      53
  ],
  pos: 5,              // Update song's position
  flag_playing: true,  // This song is now the one about to be played,
  flag_free: true,
  flag_visible: true,
  flag_accepted: true, // Accept this song
  flag_refused: false
}

Simply resolves.
Response
{
    code: 500,
    message: {
        code: 'PL_MODIFY_CONTENT_ERROR'
    }
}
Response
{
    code: 400,
    message: {
        // Validation errors here
    }
}

Up/downvote a song

votePLC Authentication needed Frontend needs to be restricted or open

Upvote or downvote a song in a playlist

Request
{
  plc_id: 2
  downvote: true // optional
}

Simply resolves.

Replace UPVOTE by DOWNVOTE in the following error message when applicable.

Response
{
    code: 404,    
}
Response
{
    code: 403,
    message: {
        code: 'UPVOTE_FAILED
    }
}

You cannot vote for a song you requested.

Response
{
    code: 403,
    message: {
        code: 'UPVOTE_NO_SELF
    }
}
Response
{
    code: 403,
    message: {
        code: 'UPVOTE_ALREADY_DONE
    }
}

Export playlist

exportPlaylist Operator user required Frontend can be closed, restricted or open

Export a playlist

Request
{
    plaid: 2
}
Response
{
    "Header": {
        "description": "Karaoke Mugen Playlist File",
        "version": 4
    },
    "PlaylistContents": [
        {
            "flag_playing": true,
            "nickname": "lol",
            "created_at": <Date>,
            "pos": 1,
            "username": "axel@kara.moe",
            "flag_free": false,
            "flag_visible": false,
            "flag_accepted": false,
            "flag_refused": false,
            "kid": "b0de301c-5756-49fb-b019-85a99a66586b"
        },
        ...
    ],
    "PlaylistInformation": {
        "created_at": <Date>
        "flag_visible": true,
        "modified_at": <Date>
        "name": "Test",
        "time_left": 0
    } 
}
Response
{
    code: 500,    
    message: {
        code: 'PL_EXPORT_ERROR'
    }
}

Import playlist

importPlaylist Operator user required Frontend can be closed, restricted or open

Import a playlist from JSON data

Request
{
    playlist: ...
}

For playlist data, see export playlist above.

Response
{
    code: 200,
    message: {
        code: 'PL_IMPORTED',
        data: {
            plaid: 5,  // newly created playlist ID
            unknownKaras: [
                'aaaaa'
            ]                // Array of KIDs unknown to the local database but available on online repositories. Array length 0 if all songs are in local database.
        }
    }
}
Response
{
    code: 500,    
    message: {
        code: 'PL_IMPORT_ERROR'
    }
}
Response
{
    code: 400,    
    message: {
        // Validation error here
    }
}

Shuffle playlist

shufflePlaylist Operator user required Frontend can be closed, restricted or open

Shuffle a playlist with a specific method

Request
{
    plaid: 2,
    method: 'normal',
    fullShuffle: false  // Shuffle entire playlist instead of only after currently playing song
}

method can be :

  • normal : Random shuffle
  • smart : Shuffle but avoids long songs close to each other, or one person having all its songs bundled together
  • balance : Creates pools of users and balances songs among the pools
  • upvotes : Sorts the playlist by number of upvotes

Simply resolves
Response
{
    code: 500,    
    message: {
        code: 'PL_SHUFFLE_ERROR'
    }
}

Create Automix

createAutomix Operator user required Frontend can be closed, restricted or open

Create an automix playlist with a set of criterias. This is similar to smart playlists but the playlsit created is static and can be modified manually.

Request
{
    filters: {
        usersFavorites: [
            axel@kara.moe,
            leonekmi@kara.moe
        ],
        years: [1982, 2003],
        tags: [
            {
                tid: '...',
                type: 8
            }
        ]
    },
    limitType: 'duration', // "songs" is another option
    limitNumber: 3600, // seconds for duration, or number of songs for songs limit type
    playlistName: 'My shiny new automix',
    surprisePlaylist: false // if true then all songs added will be hidden  
}
Response
{
    plaid: 5 // newly created playlist
    playlist_name: 'Automix 03/05/2021'
}
Response
{
    code: 500,
    message: {
        code: 'AUTOMIX_ERROR'
    }
}
Response
{
    code: 404,
    message: {
        code: 'AUTOMIX_ERROR_NOT_FOUND_FAV_FOR_USERS',
    }
}

Export playlist medias

exportPlaylistMedia Operator user required Frontend can be closed, restricted or open

Export playlist to a folder, creating a set of medias and .ass files so you can read your playlist with a regular media pleyer.

A .m3u file is also created.

Request
{
    plaid: "451569d6-cc1c-4c33-a40c-7aa8a69f7a29",
    exportDir: "/home/aterizak/myPlaylist"
}

See getPlaylsitContents command, with an extra property called exportedSuccessfully to know if any media failed its export or not.
Response
{
    code: 500,
    message: {
        code: 'PL_EXPORT_MEDIA_ERROR'
    }
}
Player Downloads