Example charm manifest: IKANDY

Rendered from app.ikandy.md • back to worked examples

A charm manifest is a small JSON file that tells MBXHub about a charm: what it is called, what it looks like, and what happens when you click it. This example describes IKANDY, a desktop application.

What it does

It puts IKANDY in 3 places you can start it from, without leaving what you are doing:

a link in MusicBee's Tools menu Tools: MBXHub: IKANDY
as a charm that can be shown on the dashboard
as a button in the HUD and the overlay Charm Bar. (Ctrl + Alt + B)

All three start the same application. The manifest launches IKANDY, it does not install it, so IKANDY has to be on the machine already — it is on Steam, with a free tier.

Using it

Download app.ikandy.json.
Put the file in your MBXHub charms folder:
- normal install: %APPDATA%\MusicBee\MBXHub\charms\
- portable install: <MusicBee folder>\AppData\MBXHub\charms\
Restart MusicBee. The Tools menu is built when MusicBee starts.

Anatomy of the example

{
  "id": "app.ikandy",
  "kind": "proc",
  "label": "IKANDY",
  "publisher": "L&R Entertainment LLC",
  "version": "0.1.0",
  "icon": "🍬",
  "launch": "steam://run/4813240",
  "launchFallback":"drive:/pathto/IKANDY/IKANDY.exe",
  "expand": [
    { "label": "IKANDY", "icon": "🍬", "placement": "menu",    "action": "launch", "msg": "Starting IKANDY…" },
    { "label": "IKANDY", "icon": "🍬", "placement": "rail",    "action": "launch", "msg": "Starting IKANDY…" },
    { "label": "IKANDY", "icon": "🍬", "placement": "overlay", "action": "launch", "msg": "Starting IKANDY…" }
  ]
}

Who the charm is

Field	In this example	What it means
`id`	`app.ikandy`	The charm's unique name. Use a publisher-style dotted name such as `com.example.thing`; a charm that registers with the hub is refused without one.
`kind`	`proc`	Where the charm's code lives. `proc` is a program on this machine. Leave it out and the charm is a `page` (HTML that MBXHub hosts).
`label`	`IKANDY`	The name people see.
`icon`	`🍬`	The emoji on the button.
`publisher`	`L&R Entertainment LLC`	Who made it. Free text.
`version`	`0.1.0`	The charm's own version. Free text; MBXHub shows it but does not compare versions.

What it starts

Field	In this example	What it means
`launch`	`steam://run/4813240`	The first thing to start: here, IKANDY through Steam. A URL scheme is handed to Windows as written.
`launchFallback`	"drive:/pathto/IKANDY/IKANDY.exe"	Tried only when the first one can't start, for example when Steam isn't installed. NOTE: you may need to replace it with the real path, such as `"C:\\Program Files (x86)\\Steam\\steamapps\\common\\IKANDY\\IKANDY.exe"` [note: `/` or `\\` is accepted as a path delimiter]

Successful dispatch never starts both targets.

Where the button appears

expand lists the charm's buttons. Each entry says where it appears (placement) and what clicking it does (action). This example puts the same button in three places:

Manifest says	Where you see IKANDY
`"placement": "menu"`	MusicBee's Tools > MBXHub > IKANDY
`"placement": "rail"`	The charm rail on the dashboard web page
`"placement": "overlay"`	The HUD and the Charm Bar (Ctrl+Alt+B)

In every entry:

action: "launch" starts the charm, using launch and then launchFallback. The word takes no target of its own; the targets live only at the top of the manifest.
msg is the status text shown when you click.

When a launch is allowed

Launching happens only from the machine running MusicBee.
A manifest you put in your own charms folder, with no registration, may launch its targets.
Some URL schemes are always refused, including http, https, file and anything starting ms-.
If the operator narrows the allowed schemes, steam has to be on that list.
If Require registration for charms is on (MBXHub settings, API Access tab), a manifest that was never registered does not launch.

The full manifest reference is in llms.txt, under Manifest fields, Manifest registration fields and Placements, and how an activation reaches a charm.