KaraFun Player Control API

General information

Communications between your software and KaraFun Player are made through TCP WebSockets. A socket server is running at all time when you have an active subscription in KaraFun Player (which must be started and running) and listening on port 57570 by default. Your software must behave like a socket client and send actions (see the list below) and messages to KaraFun Player.

• Volume values are between 0 (muted) and 100 (full volume)
• Time and duration values are in seconds (can be float)
• Colors are in HTML format #RRGGBB

List of actions

• Get player status
• Get the list of catalogs
• Get a list of content
• Search
• Audio control & transport
• Manage volumes
• Manage song queue

Get player status

<action type="getStatus" [noqueue]></action>

Reflect the current state of KaraFun Player. `no queue` allows not to send the queue status.

---

Response to getStatus

<status state="{player_state}">
                        [<position>{time_in_seconds}</position>]
                        <volumeList>
                        <general caption="{caption}">{volume}</general>
                        [<bv caption="{caption}">{volume}</bv>]
                        [<lead1 caption="{caption}" color="{color}">{volume}</lead1>]
                        [<lead2 caption="{caption}" color="{color}">{volume}</lead2>]
                        </volumeList>
                        <pitch>{pitch}</pitch>
                        <tempo>{tempo}</tempo>
                        <queue>
                        <item id="{queue_position}" status="{item_state}">
                        <title>{song_name}</title>
                        <artist>{artist_name}</artist>
                        <year>{year}</year>
                        <duration>{duration_in_seconds}</duration>
                        [<singer>{singer_name}</singer>]
                        </item>
                        ...
                        </queue>
                        </status>

`<volumeList>` general is always included, disabled volumes are not included
`<queue>` item count is limited to 100 (approx 5 hours of queue!)
`player_state` possible values :

• idle
• infoscreen
• loading
• playing

`item_state` possible values :

• ready
• loading

Get the list of catalogs

<action type="getCatalogList"></action>

List currently available catalogs. Queue, history and tree structure are not included.
`type` possible values :

• onlineComplete
• onlineNews
• onlineFavorites
• onlineStyle
• localPlaylist
• localDirectory

---

Response to getCatalogList

<catalogList>
                        <catalog id="{unique_id}" type="{type}">{caption}</item>
                        <catalog id="{unique_id}" type="{type}">{caption}</item>
                        ...
                        </catalogList>

Get a list content

<action type="getList" id="{list_id}" offset="{offset}" limit="{limit}"></action>

List the songs of a catalog
Default `limit` is 100

Search

<action type="search" offset="{offset}" limit="{limit}">{search_string}</action>

List the songs of a search
Default `limit` is 100

---

Response to getList/search

<list total={total}>
                        <item id="{unique_id}">
                        <title>{song_name}</title>
                        <artist>{artist_name}</artist>
                        <year>{year}</year>
                        <duration>{duration_in_seconds}</duration>
                        </item>
                        ...
                        </list>

Audio control and transport

<action type="play"></action>
                        <action type="pause"></action>
                        <action type="next"></action>
                        <action type="seek">{time_in_seconds}</action>
                        <action type="pitch">{picth}</action>
                        <action type="tempo">{tempo}</action>

Volume management

<action type="setVolume" volume_type="{general|bv|lead1|lead2}">{volume_between_0_100}</action>

You can find the currently available volume types from the getStatus query

Song queue management

<action type="clearQueue"></action>
                        <action type="addToQueue" song="{song_id}" singer="{singer_name}" >{add_position}</action>
                        <action type="removeFromQueue" id="{queue_position}"></action>
                        <action type="changeQueuePosition" id="{old_position}">{new_position}</action>

`song_id` and `queue_id` are unique
`singer` is optional in addToQueue query
`position` possible values :

• 0: top
• 1...n: specific position
• 99999: bottom